
  ***** The GGZ Gaming Zone 0.0.14 - Hosting Guide *****
  *** Instructions and Recommendations for Server Hosters ***

  Author: GGZ Development Team

  Copyright (C) 2001 - 2006 Josef Spillner.
  Published under the GNU General Public License.


  @ifnottex

  @top Menu
  @end ifnottex

  This file is the info format of the GGZ Gaming Zone Hosting Guide, which is
  also available in postscript and HTML format.
  It describes how to setup a GGZ server and how to configure and maintain it.
  See http://www.ggzgamingzone.org/docs/guides/hosting/ for the latest edition.

Menu:
  * Foreword:: General notes about this document
  * Game Servers:: History and Diversity
  * Installation:: How to prepare and survive a GGZ installation
  * Databases:: Where to store player information
  * Internal Games:: Description of available games
  * External Games:: Additional games for GGZ
  * Other GGZ Servers:: How to install the Meta Server and TelGGZ
  * GGZ Server Tools:: Make an admin's life easier
  * Server Maintainance:: Help for administrators
  * Local GGZ server installation:: Appendix 1
  * Known GGZ servers and Contact:: Appendix 2

Chapter: Foreword

  Over the last years the hosting of free gaming servers has turned into a task
  which sometimes demands skills and time effort by the server hoster. The games
  are becoming more complex, the infrastructure grows, and inter-server
  communication, such like metaservers, starts a new era of free multiplayer
  gaming.

  This guide helps people to set up servers. It is specifically targeted at GGZ
  servers, but contains some general material as well, mostly because setting up
  a full-featured GGZ server involves the installation of many different games.

  Feel free to ask if something is in doubt. The GGZ Gaming Zone Development Team
  does its best to keep this guide always up-to-date and tries to avoid any
  errors and typos, but this is a very new topic and may take some time to
  stabilize.
  Contact information is provided in the appendix.

Chapter: Game Servers

  The traditional approach is to have game servers running permanently on a host,
  and let players connect to them using their game clients. Usually the server
  does then spawn a new process for each started game, which exits when all
  players have left the game.
  Permanent game servers are a variant of this: for example, role-play games do
  often only consist of one process which never ends, and players may join and
  leave whenever they wish.
  GGZ does now support permanent game servers too; see the
  section about the game Keepalive below.

Chapter: Installation

 Section: The impact of a GGZ installation

  In the old days, installing GGZ meant installing the @b{ggz-server} package
  which contains the main GGZ server [ggzd] and a variety of
  game servers. Since then, more software has been produced which makes
  a GGZ installation the centerpiece of gaming communities.
  The more software is installed, the more time-consuming the maintenance
  will be. However, as player demands grow, there is often no way around
  a full installation.
  This guide will try to give a balanced view so that both ends of the
  spectrum can be evaluated and a customized installation will be the
  result.

 Section: Prerequisites

  On some Linux distributions, the GGZ server can now be installed as a binary
  package which already comes preconfigured. However, sometimes it just doesn't
  provide the correct choice, as many aspects of the server's features must be
  decided on at compilation time. Have a look at the output of
  [ggzd --specs] or [ggzd -s] to know what features it provides.

  The following sections describe the compilation and installation of
  [ggzd] in case this is appropriate.
  It is however also of interest to those who use
  pre-installed packages as it gives a lot of hints for how to operate a GGZ
  server and the associated tools. More on that is explained in later chapters
  about tools and administrative tasks.

 Section: Overview

  This section describes a typical setup for GGZ 0.0.14.
  Future versions might require other tools or other versions of
  the present one, but the main concept hasn't changed for a while.
  Before installing GGZ on a server, make sure that the following conditions are
  met:

   * The server has its base system installed. This includes everything needed
  by the @file{configure} script of [ggzd], the locales and preferably
  a dedicated system account for GGZ. A database system is also needed for full
  SQL-based GGZ installations, although it doesn't have to run on the same host.
   * Network connectivity is present. At least port 5688 must allow incoming
  connections.
   * Libraries and development packages (including headers) are installed
  according to the requirements given in the release information; at present,
  this is:

   * libdb 4.x (or former versions), or mysql or postgresql or sqlite
   * gettext and getopt (should be part of glibc on most systems)
   * libexpat
   * howl or avahi (optional, for LAN zeroconf broadcasts)
   * fam or inotify (optional, for dynamic room reconfiguration)
   * libgcrypt (optional, via libggz, to handle hashed database passwords)
   * libgnutls or libopenssl (optional, via libggz, to handle encrypted connections)

   * Depending on the support of external games or scripting plugins,
  the following is also recommended:

   * gnugo
   * gnuchess
   * gnushogi
   * libxml
   * python
   * perl

   * More game engines can be installed to improve the experience of the
  players. This will be covered in the chapter about the individual game
  servers.

 Section: Hardware requirements

  You should calculate a need of about 20-30 MB of initial disk space, which
  might however not be enough if the server runs over a long time, as log files
  and savegame files are being added.
  Memory is normally not an issue, even old server hardware with only 32 MB of
  RAM should be sufficient. The same goes for the CPU - a GGZ server with less
  than 100 people on it can be handled by any Pentium-class or better CPU.
  Network bandwidth is difficult to estimate, as each game requires a different
  amount of it. But the first GGZ development server, once connected by 56k,
  handled a few players and games at the same time quite well, so there's no need
  for high bandwidth under normal circumstances.
  More detailed calculations, including real-time games and measurement/control
  tools will follow later.

 Section: Base installation

  This rather large section covers the minimum software installation and
  configuration to get a GGZ server going. This includes the @b{libggz}
  and @b{ggz-server} packages, among others, the MOTD file and the main
  configuration file.

  Before the main server ([ggzd]) can be installed, its dependencies must be
  resolved. The GGZ package @b{libggz} is currently the first such
  package; this replaces the @b{easysock} package which was used up to version
  0.0.4. It provides GGZ software written in C with networking and other
  functions.
  After libggz is installed, the server packages @b{ggzd}, which is the main
  server, and @b{ggz-game-servers} including many game servers, should follow.
  Both need the library package @b{ggzdmod} and its C++ wrapper @b{ggzdmod++}
  as well.
  When installing from source, all of those can be found in the @b{ggzd} SVN
  module which gets packaged under the name @b{ggz-server}.
  In addition, the @b{ggz-python} package provides the @b{pyggzdmod} wrapper
  library and a couple of game servers on top of it, so its installation is
  recommended as well.

  Section: Building the GGZ library

  If libggz is built from sources, the features it provides can be customized.
  Running [configure --with-gcrypt] allows for cryptographics hash
  functions to be used, so that e.g. the server doesn't need to store its
  passwords in plain text format into the user database.
  Likewise, [configure --with-tls=TYPE] includes TLS/SSL functionality,
  which can be one of none (dummy support), GnuTLS or OpenSSL.
  Enabling TLS is mandatory if encrypted connections should be provided
  to players.
  The part about setting up the server covers this topic in depth.

  Section: Building the GGZ server

  After having installed libggz, the GGZ server can be installed.
  The prefix can be changed for installations from source code when running
  [./configure --prefix=/usr/local/ggz], for example.
  Likewise, [--sysconfdir] may be used to specify the location for
  configuration files.
  When installing into an uncommon prefix, such as a home directory, the
  dependencies are found automatically if they are located in the same prefix
  or in the common prefixes @file{/usr} and @file{/usr/local}. If this is
  not the case, GGZ dependencies can be forced to be found by adding
  [--with-ggz-dir=DIR] to the @file{configure} script.

  The options [--with-zeroconf] and [--with-reconfiguration]
  can either enforce or disable the choice for a certain library which is
  used by [ggzd]. If not given, the best choice is selected
  automatically and missing libraries result in lack of functionality.
  The database backend choice can also be enforced, but not disabled, since
  [ggzd] always needs a database to function correctly.
  Therefore, the following would be a valid custom configuration command:

  ./configure --without-reconfiguration --with-zeroconf=howl \
    --with-database=pgsql \
    --with-ggz-dir=/home/ggz/installation --prefix=/tmp/testinstall

  Although normally the server hierarchy will be under @file{/usr} or
  @file{/usr/local}, there are situations where someone doesn't have root access
  on a system to install the GGZ packages there.
  This is no problem, installing into one's home directory is supported as well
  as can be seen above.
  For installations from source tarballs, the [getggz.sh] script is
  recommended, because it handles this task very fast in an interactive way.
  Its location is pointed at in the current installation manual.
  This script, together with several others, will eventually be part of a server
  support package.
  For the time being, it is presented in a simplified version in Appendix A.

  For installations from SVN, the [ggzbuild] script is the better
  choice. The GGZ Game Development Guide contains an introduction.

  Upon installation, lots of files and directories are created under the
  chosen prefix (usually @file{/usr/local} when installing from source and
  @file{/usr} otherwise), assuming the paths were not customized when
  calling the @file{configure} script:

   * etc: configuration of ggzd and game registry; message of the day (MOTD)
   * bin: ggzd executable
   * lib/ggzd: game servers
   * share: game server data and level files
   * var/ggzd: dynamic data such as players and statistics (if not present yet, it
  is created on startup), and dynamic game data

  Section: Message of the day

  GGZ clients will request a message of the day (MOTD) from the server after
  each login. There are two variants of MOTDs, text-based (the default) and
  optionally a HTML-based one in addition, which points to a web page.
  The text MOTD file is usually stored in @file{etc/ggzd/ggzd.motd}. Its
  path is configured in @file{ggzd.conf} and should be changed for customized
  MOTDs so a server update won't overwrite the default MOTD.

  As each server should be unique in one way or the other, changing the MOTD
  (which the players read when they log in) is one of the first steps to be made.
  C-style variables place holders can be used, they are currently defined like:

   * %a: server administrator's name
   * %c: color switch; must be followed by a number between 0 and 9
   * %C: server CPU type
   * %d: current date
   * %e: administrator's email address
   * %g: current number of game tables
   * %G: current number of game tables with open seats
   * %h: server hostname
   * %o: server operating system
   * %p: server port
   * %t: time zone (local time)
   * %u: server uptime
   * %U: number of users logged in
   * %v: GGZ server version number

  You can use premade MOTDs which are available from the @file{motds} directory
  of the @b{ggz-utils} package.
  In addition, the @b{ggz-gnome-client} package provides an application named
  [motd-editor], which can be used to graphically edit such MOTD files,
  while having a real-time preview of the colour settings.

  Section: Widely used terms

  Before proceeding to the configuration part, a few terms shall be presented
  first so that their understanding will be easier and misconfigurations
  can be avoided.

  The GGZ @emph{server} provides different @emph{rooms}. Just like in a big
  house, a player can only be in one room at a time. Each room has a special
  purpose, and like there are kitchen, bedroom and entrance in a real house,
  there are rooms for TicTacToe, Chess and Hastings in a game server. To enhance
  this analogy: Many houses have, say, two bathrooms with different interieur. So
  a GGZ server administrator can set up a small TicTacToe room for 10 people
  called 'TTT Newbies' with a restricted set of maximum 2 tables, and a larger
  one for 50 people tagged 'TTT Tournament' and no further restrictions.
  Therefore, each room is linked to exactly one @emph{game type}. Based on these
  types, players start to play their @emph{games} by creating @emph{tables}.
  Each table can hold 2 to unlimited players, dependent on the room setup.
  At present time, however, the maximum number of players is restricted to 8 or
  less for most games.

  Some rooms do not have games associated with them. In the default case,
  this affects the entry room or @emph{lounge}, but it might also apply
  to some rooms reserved for server administrators.

  Section: Main GGZ server configuration

  The main GGZ server (ggzd) is configured by a single file, named
  @file{ggzd.conf}. The default values are fine for testing and running a few
  games, but it is strongly recommended that server administrators check all
  values contained in the file.
  For example, the administrative contact information or the server-client
  communication encryption should be customized.
  When running a GGZ server on a desktop system, it will be possible to configure
  the server graphically in the future. A KDE control center module is already
  available for reading in configuration files. It is part of the
  @b{ggz-kde-client} package.

  For configuration tests, it is recommended to enable logging and debugging in
  the configuration file, and then run [ggzd -F] to make it stay in the
  foreground.

  Section: Reconfiguration

  From GGZ 0.0.14 on it is possible to add and remove rooms during the
  execution of ggzd, meaning that the server does not need to be interrupted for
  such reconfiguration tasks. This is useful for larger GGZ sites which at
  times even allow their users to define new rooms via a web interface.

  Enabling the reconfiguration feature means that support for it must have
  been compiled into ggzd (as can be verified with [ggzd -s]), and
  that it has been enabled in ggzd.conf via the switch ReconfigureRooms, which
  is disabled by default.

  See the section named 'Adding rooms' for more information on room files.

 Section: Normal installation

  The base installation is usually sufficient for game developers to test
  their game servers.
  Despite this, a ggzd alone is not much fun, there are other components as well
  which are worth to be installed:

   * The GGZ Metaserver
   * Grubby, the GGZ chat bot

  In a later chapter the details on how to install these are explained.

 Section: Extended installation

  Some programs are only installed by very few people, mostly because they are
  very specialized. TelGGZ, the telnet wrapper which allows world-wide
  participation in GGZ chat sessions over the telnet protocol, is one such
  candidate.

  Some external games require additional programs or tools, see the games
  section later on.

  The GGZ Community portal allows for web access to statistics, player lists,
  password reminders and more. It is not available as a binary package yet, but
  a source package named @b{ggz-community} already exists.
  It is designed to work with a PostgreSQL database backend, and requires Apache
  and PHP set up on the same or any different host.
  Lots of additional software like a forum or a blog aggregator can be integrated
  into GGZ Community.
  The reference installation runs on <<http://www.ggzcommunity.org/>>, but
  other server operators can use the software and its features like custom themes
  to create own instances, to shape local communities or dedicated player clubs.

  GGZ Community has its own configuration file, but most of the important
  settings can be read from @file{ggzd.conf}.

  The browser-based GGZ-Java applet and its associated application, which comes
  with a webstart description, might lure more players to a server than the
  existing clients for KDE, GNOME and SDL. Its installation can be integrated
  with GGZ-Community.

  Metacle is a new service, which was brought to life during the GGZ 0.0.14
  release cycle. It aggregates metaservers such as the one of GGZ, but also
  others, and feeds this data to client applications. Metacle is not yet part
  of a GGZ package, but is available from the playground module in SVN.

  Have a look at the next chapter on how to set up GGZ with enhanced database
  support to prepare an extended installation including GGZ Community.

Chapter: Databases

 Section: Database choices

  The GGZ server is able to store its data in various database formats.
  Currently, not only the traditional libdb format is supported (db2, db3 and
  db4), but also SQlite, MySQL and PostgreSQL. The latter ones are more difficult
  to set up, but provide greater flexibility because there exist a lot of
  standard tools to use the data in them.
  In addition, a DBI backend exists which can in turn talk to a variety
  of database installations including PostgreSQL and SQlite.
  GGZ Community uses PostgreSQL, if in doubt this database should be used.

  There are three basic database table sets: one for the players (including passwords,
  email addresses, permissions and full name), one for the statistics generated
  by games played on the server and player and team information, and one for
  tournaments.
  More tables can be created for extended installations. The @b{ggz-community}
  package contains all the necessary SQL schema files in the directory setup/sql.

 Section: Embedded databases setup

  When using libdb or SQlite, nothing special has to be done.
  For explicit support of a certain version number, running configure with
  [--with-database=db4] or similar when installing from source is
  sufficient. The server cares about creating and managing the database.

 Section: SQL setup

  For extended GGZ installations, using embedded databases is not recommended.
  Instead, SQL databases with remote access from standard tools should
  be used. They are more difficult to set up but way more powerful once
  this is done.

  The libdb databases are stored in ggzd's variable datadir (usually
  @file{/var/ggzd}), whereas SQL databases can even be located on other hosts.
  To set them up, make sure ggzd has support for them compiled in (using
  [--with-database=mysql] or [pgsql]), and setup the following
  values in ggzd.conf within the [General] section:

   * DatabaseHost
   * DatabaseName
   * DatabaseUsername
   * DatabasePassword
   * DatabaseHashing
   * DatabaseType

  The hashing can be one of plain, md5, sha1 or ripemd160. If encryption support
  is missing in libggz, it automatically falls back to plain text.
  If database hashing is activated, users can only request new passwords upon
  forgetting the old one, instead of having the old one resent to them.

  The setup of both MySQL and PostgreSQL databases will now be explained
  in detail.

 Section: MySQL configuration

  If ggzd uses MySQL as its database, the data structures are initialized
  automatically, but a database user and the database itself must be created
  prior to starting the server.
  To accomplish this, the tool [mysql_setpermission] should be used.
  When running this program as the database superuser, selecting the second menu
  entry leads straightforward to a ready-to-use database.

  If the MySQL server runs on a different host than the ggzd server, the
  skip-networking option in @file{my.cnf} must be disabled.

  Note that the MySQL backend is not complete at the moment, as it is not used
  much.

 Section: PostgreSQL setup

  When using PostgreSQL, a dedicated GGZ user and database has to be created.
  From PostgreSQL 7.3 on, the following commands should be used:

  	psql template1
  	CREATE USER ggzd PASSWORD 'xxxxx';
  	CREATE DATABASE ggz OWNER ggzd ENCODING 'UNICODE';

  For versions below 7.3, things are more difficult, especially since the
  table cannot be created automatically. Thus, the following applies:

  	psql template1
  	CREATE USER ggzd;
  	CREATE DATABASE ggz;
  	\q
  	psql ggz
  	CREATE TABLE users (
  		id serial NOT NULL,
  		handle varchar(256) NOT NULL,
  		password varchar(256),
  		name varchar(256),
  		email varchar(256),
  		lastlogin int8,
  		permissions int8
  	);
  	CREATE TABLE stats (
  		id serial NOT NULL,
  		handle varchar(256) NOT NULL,
  		game varchar(256) NOT NULL,
  		wins int8,
  		losses int8,
  		ties int8,
  		forfeits int8,
  		rating double,
  		ranking int8,
  		highscore int8
  	);
  	CREATE TABLE control (
  		key varchar(256),
  		value varchar(256)
  	);
  	GRANT ALL ON users TO ggzd;
  	GRANT ALL ON users_id_seq TO ggzd;
  	GRANT ALL ON stats TO ggzd;
  	GRANT ALL ON stats_id_seq TO ggzd;
  	GRANT ALL ON control TO ggzd;

  The control table is used internally by ggzd to detect upgrades.
  You can speed up the table with an index, like:

  	CREATE index xhandle ON users (handle);

  Make sure the connection can be established. When the database is running on a
  remote server, it must accept internet connections (startup option -i), and
  allow the remote access, which could be granted using the following entry in
  @file{data/pg_hba.conf}:

  	host ggz 192.168.0.2 255.255.255.255 crypt

  Please refer to the PostgreSQL documentation for tuning and security advice.
  The above information is only meant as a quick setup, not as complete
  documentation. As already mentioned, the SQL files from the @b{ggz-community}
  package should be used eventually.

 Section: Format

  The database format of the user table is the same for every configuration.
  Limits on string length or integer number size are more relaxed with the
  SQL database backends, but the limits below should be considered minimum
  guaranteed sizes.

  id/user_id: unsigned int (4 bytes), must be unique
  handle: string (currently 16 bytes), must be unique
  password: string (16 bytes)
  name: string (32 bytes)
  email: string (32 bytes)
  last_login: time_t/unsigned int (4 bytes)
  first_login: time_t/unsigned int (4 bytes)
  perms: unsigned int (4 bytes), interpreted as a bitfield

  The first_login field has been added in GGZ 0.0.14 and is not
  yet used by [ggzd] itself.

 Section: Administration

  The player database can be administered using the tool [ggzduedit],
  especially when not using one of the SQL databases which usually come with
  query tools (it does however support those too).
  The statistics database generally doesn't need to be changed during its
  lifetime.
  There is a separate description of [ggzduedit] in the chapter about
  server tools.

 Section: Integration and synchronization

  Having GGZ Community installed almost always means offering web-based
  forums to the players. The forum software used by GGZ Community is
  phpBB2 which uses its own database.

  In order to keep the user lists consistent, all phpBB users are
  only copies of the GGZ users. The phpBB database is updated whenever
  the GGZ database changes. This can happen periodically using the
  [ggz2phpbb.pl] script. However, GGZ 0.0.14 introduces a
  server-side trigger for PostgreSQL databases which lowers the
  load and eliminates the delay in the propagation of changes to
  the GGZ database.

  More information is available in the file @file{setup/sql/trigger}
  within the GGZ Community sources.

Chapter: Internal Games

 Section: Scope

  We call all the games which come along with GGZ @emph{internal games}. This
  expresses that they have been designed to work with GGZ, and make extensive use
  of the possible options which the GGZ server offers to them. This currently
  includes game statistics, rankings, game spectators, selectable AI players,
  table management and more.
  In the future this will include saved games, data updates and more.
  Many players expect the internal games to be installed on every server, and
  this is highly recommended. For development and analysis of games they provide
  very good examples, ranging from a simple tic-tac-toe game to more complex ones
  with different protocols.

  The @emph{internal game servers} are included in the @b{ggzd} SVN module
  of GGZ in the @file{game_servers} directory. Alternatively, binary packages
  named @b{ggz-game-servers} exist in many Linux distributions.

  Each game server has its homepage with links to corresponding clients
  and the game protocol in use on the page:

  <<http://www.ggzgamingzone.org/gameservers/<gameservername>>>

 Section: Server-side game data storage

  From release 0.0.6 on, each game has been storing its dynamic data within the
  hierarchy of ggzd's variable data dir, e.g.
  @file{/var/ggzd/gamedata/<gamename>}.
  All the directories there are created automatically, if they are missing after
  the server start something went wrong.

  Right now, some games like Tic-Tac-Toe and Dots store savegames in their
  respective directories. If the base directory is added to the configuration
  of GGZ Community, reviews of past games will be offered, and the savegame
  files can be downloaded for replay in those game clients that support it.

 Section: Other game features

  In addition to savegames, some games support @emph{named bots}, that is,
  the selection of a certain AI player based on its name. The way the feature
  works is that a game's description file contains the names which are
  registered as bots in the GGZ user database upon loading the description
  file for the first time.

  Both savegames and named bots will be mentioned for each of the following
  games whereever applicable.
  More features like game spectators can be found in a game server comparison
  matrix which is installed as part of the @b{ggz-docs} package, and
  on the beforementioned game server homepages.

 Section: Overview on the games

  Section: Chess

  This is the GGZ variant of the chessd server, which is developed using the
  cgc library from <<http://chessd.sourceforge.net>>, like the chessd Fischer
  server. This library is a static one, just like the GGZ chess AI library
  @emph{libggzchess}, so no further dependencies are needed.

  If GNU Chess is installed, selecting its corresponding AI player personality
  enables the users to play against it. This is a @emph{named bots} feature.

  The chess server can save games in the PGN format.

  Section: Chinese Checkers

  A chinese checkers game for 2-6 players.
  It provides an internal AI player. No advanced features are available.

  Section: Chinese Chess

  A chess game using the chinese game rules, for 2 players. This server with
  the name @emph{Xadrez Chines} is written in Python and thus requires a
  python interpreter and the respective GGZ library wrappers on the server.
  @strong{It is not part of the ggz-server package, but of ggz-python instead.}
  The AI is provided through the @emph{xadrezlib} library.
  No advanced features are available.

  Section: Combat

  This is the server for the strategy game Combat for 2 players.
  It provides an internal AI player.
  No advanced features are available.

  Section: Connect the Dots

  A Connect the Dots server for GGZ.
  Dots can save games under its own format.

  Section: Escape

  The escape server serves the Windows game client Escape and its SDL port, see
  <<http://wggz.sourceforge.net>> for details.
  No advanced features are available.

  Section: GGZCards

  This is a special game, it provides different game servers for one game client.
  The following games are currently supported: Bridge, Euchre, Hearts, LaPocha,
  Spades, Suaro, Sueca, Whist and FortyTwo.
  There will be more in the future, for example Skat or Mao.
  Each game provides its own description file.

  No savegames or named bots are available.

  Section: Go

  This is a hybrid internal/external game server. The game server itself is
  GNU Go from <<http://www.gnu.org/software/gnugo/>>.
  However the GGZ launching part is installed by default. It requires a Python
  interpreter and the respective GGZ library wrappers.
  @strong{It is not part of the ggz-server package, but of ggz-python instead.}

  The Go server communicates with the Go Modem Protocol (GMT).
  It provides no additional features.

  Section: Hastings1066

  Strategy game for 2-8 players. Includes text files which represent maps,
  and are sent to the client depending on the map selection.

  No advanced features are offered.

  Section: Keepalive

  This game is currently in experimental stage. It has been invented as a
  proof-of-concept to lower the barriers of enhanced game development, including
  game spectators, eternal runtime and a more complex server-side design.
  It writes player data into a subdirectory of ggzd's variable data directory.

  Keepalive is the only C++ game server in GGZ which uses the pure ggzdmod
  library instead of ggzdmod++ or another wrapper.
  No advanced features are offered.

  Section: Krosswater

  Krosswater is written in C++ and uses its own library libzoneserver, which
  should be taken care of when installing locally. If the installation is not
  done properly, lots of ghost tables will show up after some time.

  Section: LaPocha

  A card game server. The original LaPocha server has been discontinued, as
  the GGZCards-LaPocha server module provides the same functionality.

  LaPocha is now available only through GGZ's graveyard. Information is
  available on <<http://dev.ggzgamingzone.org/graveyard/>>.

  Section: Muehle

  The Muehle server is not yet a full server, it only handles game initialization
  for Muehle (Nine men's morris), and passes the game data between the clients.

  Section: NetSpades

  A card game server for the NetSpades game which has been derived from the
  former non-GGZ NetSpades.
  It is the only GGZ game server which does not use the ggzdmod library.

  Section: Reversi

  Game server for the reversi game.

  Section: Tic-Tac-Toe

  The easiest game, which does therefore serve as an example for beginners in GGZ
  game development. This game has most clients available for testing.

  The Tic-Tac-Toe server thus supports named bots and savegames.
  It also supports game resumes, record-style statistics and other features.

  There is an alternative Tic-Tac-Toe server available as a ruby implementation
  dubbed RubyToe. It is not yet installed by default.

  Section: Geekgame

  A game server written in C++ for which an SDL client exists. It has been
  designed from scratch and involves a game board on which certain mathematical
  combinations must be reached.

  Section: Tuxman

  This server is used by the external game client Tuxman (formerly Wolf-Pacman),
  which is available at <<http://dak0r.de/~badwolf/ftpnet/badwolf/tuxman/>>.

  At the moment, the Tuxman game seems to be dead. Therefore, the Tuxman
  server will probably be discontinued in the future. It is one of the very
  few ones of the real-time game genre (together with Keepalive).

  Section: Checkers

  The Checkers game is sometimes referred to as Draughts.

  @strong{It is not part of the ggz-server package, but of ggz-python instead.}

  Section: Hnefatafl

  Hnefatafl is an old nordic game.

  @strong{It is not part of the ggz-server package, but of ggz-python instead.}

  Section: RubyToe

  RubyToe is a reimplementation of the TTT game server in Ruby. It is not yet
  officially part of any GGZ package, but can be retrieved from the Playground
  SVN module.

  Section: Ludo

  Ludo is a board game for four players. A simple game server is available.

  @strong{It is not part of the ggz-server package, but of ggz-python instead.}

  Section: ConnectX

  ConnectX or Four Wins is a board game for two players. The GGZ server
  provides the Velena AI engine as a named bot in addition to its own internal
  AI player. The Velena engine must be installed for this to work correctly.
  A helper script is available from GGZ SVN in the directory
  @file{playground/server/games}.

Chapter: External Games

 Section: Scope

  Games developed independent from GGZ, for example games which existed for a
  long time already and have just recently been ported to run on GGZ servers,
  are commonly called @emph{external games}. Their installation base is varying,
  although it is not very difficult to support these games as well.
  All major GGZ servers should include all of them to give their players a
  better choice.

 Section: Availability

  See <<http://www.ggzgamingzone.org/games/>> to
  view the list of external games. The former method of retrieving patches is no
  longer necessary; a sufficiently large number of external games does now provide
  GGZ support.

 Section: Description of available external games

  Section: GNOME Games

  The GNOME Games package provides a whole suite of desktop games. Starting
  from GNOME version 2.18, a number of them can be played on GGZ.
  As of now, this includes the games Iagno, Gnect and Gnibbles.

  The Gnect game corresponds to GGZ's ConnectX server whereas Iagno is
  a Reversi game. Gnibbles does not have an equivalent in GGZ.
  All three of them ship their own game server as part of GNOME Games.
  It remains to be seen if the games will work out of the box with the
  servers shipped with GGZ in the future.

  See <<http://www.gnome.org/projects/gnome-games/>>.

  Section: Batalla Naval

  This is a graphical server using the GNOME libraries, so it is only of interest
  for people who run a GGZ server on a desktop system or install all the necessary
  libraries.
  It has GGZ support built-in.
  See <<http://batnav.sourceforge.net>>.

  @strong{Batalla Naval does not seem to be maintained anymore.}

  Section: Freeciv

  From version 2.1 on, Freeciv comes with integrated GGZ support, including
  game spectators and statistics.
  A possible configuration is:

  @command{./configure --enable-client=no --with-ggz-server
  --with-ggzdmod-dir=$prefix
  --with-ggzmod-dir=$prefix
  --with-ggzconfig=$prefix/bin
  --prefix=$prefix}

  <<http://www.freeciv.org/>>

  Section: T.E.G.

  T.E.G. is a GNOME game, which has GGZ support built-in. The server needs
  libxml2 and libglib 1.2 installed.
  Be sure to alter the include paths if necessary when compiling from source.
  <<http://teg.sourceforge.net>>

  Section: Kamikaze

  Similar to Bombermaze or Clanbomber, Kamikaze provides fast action for either
  KDE (on the desktop) or OPIE (on handhelds). The desktop version has support
  for GGZ so 1-8 players can join in a level, with up to each but one of them being
  bots.

  <<http://kamikaze.coolprojects.org/>>

  Section: Freelords

  Freelords started to get GGZ support from version 0.3.6. on.
  However the general networking support is still in its infancy, and thus no
  recommendation can be given here. Under normal circumstances, a GGZ
  installation should be detected automatically.

  <<http://www.freelords.org/>>

  Section: Widelands

  In Widelands, one of the game clients acts as game server. Only a small server
  handles the GGZ liaison, and since it is part of the ggz-server package, no
  further efforts have to be taken to allow Widelands games over GGZ.

  <<http://www.widelands.org/>>

  Section: Copenhagen

  This game was developed around GGZ 0.0.5, however it was not included due
  to stability issues. It can still be installed from source however, but
  it will likely not work.
  <<http://mindx.sourceforge.net>>

  Section: Others

  Other games like bzFlag, XTux Arena or Stalker were once among the prospective
  candidates, however they are either not developed any further or the GGZ patches
  never made it into the source tree and thus went unmaintained.

Chapter: Other GGZ Servers

 Section: The GGZ Metaserver (ggzmetaserv)

  This is an XML based service which allows clients to connect to select between
  several servers, without having to manually configure all of them. Metaservers
  operate in networks and keep themselves consistant automatically, so that both
  a broken GGZ server and a broken GGZ Metaserver doesn't annoy that much.
  Meta servers can be installed quite forward, no further configuration is
  necessary - all of the initial setup is read from a single read-only
  configuration file named metaservconf.xml.
  However, during operation a cache file named $HOME/.ggz/metaserver.cache is
  created which contains the URIs of other meta servers, so the network can grow
  dynamically.
  The metaserver allows for write access for all domains (combination of class
  and category) which are explicitely marked as such.
  It runs on port 15689 by default, but any other port can be used of course.
  You can get ggzmetaserv as part of the GGZ utils package.

  The webpage of grubby is <<http://www.ggzgamingzone.org/backend/metaserver/>>.

 Section: The GGZ Telnet Wrapper (telggz)

  This server requires the ggzcore library to be installed on the server side,
  just like grubby. It also uses the meta server, which doesn't have to be
  available on the same host, but the metaserver.cache file must be available
  (see comments on the meta server).
  TelGGZ should be invoked over (x)inetd on port 15688. This allows to connect to
  any GGZ server from all over the world, whereever one finds a telnet client.

  The webpage of grubby is <<http://www.ggzgamingzone.org/clients/telnet/>>.

 Section: The GGZ Chat Bot (grubby)

  Grubby comes with its own manuals, including an administrator's manual and a
  user's manual, as part of the GGZ documentation package.
  While grubby can also run client-side (as it is in fact a GGZ client), it makes
  much more sense to have it running permanently on the server side to take
  advantage of its facilities like logging or memorizing things.
  It can also play games (like TicTacToe or Chess).

  The webpage of grubby is <<http://www.ggzgamingzone.org/backend/grubby/>>.

 Section: The GGZ Collector (ggzcollector)

  A python-based standalone server which listens on port 5699 by default.
  Its task is to receive XML-formatted messages which contain the (untrusted)
  highscores of games which do not run over GGZ, but still might want to
  use its highscore or rating facilities.
  Note that this program is not distributed yet, but can be retrieved from
  the Playground module in GGZ SVN.

 Section: The Metacle

  Metacle can be regarded as a meta-metaserver. It aggregates the data
  from several metaservers and offers it in a unified format to its clients.
  Supported metaservers include the GGZ metaserver (of course), the Freeciv
  metaserver, the one of Liquidwar, of WorldForge and others.

  Metacle is still under development. A test installation is running at
  <<http://metacle.ggzgamingzone.org/>>.

Chapter: GGZ Server Tools

 Section: The ggz-cmd command line utility

  Admins are allowed to broadcast messages to all rooms via the /wall command.
  To do that from the command line, for example to announce that a server will go
  down in a few minutes, the utility [ggz-cmd] can be used.
  It is available from the @file{utils/cmd-client} directory, or as part of a
  @b{ggz-utils} package.

  An example on how to use ggz-cmd on a server (the specified user must be
  registered as administrator, using [ggzduedit], see below):

  [ggz-cmd localhost admin adminpassword announce \]

  ["Attention, server reboot in five minutes"]

  Also, when running via cron, it can be used to report the status of the server.
  The 'checkonline' command has been invented for this task.

  [ggz-cmd localhost admin adminpassword checkonline]

  Administrators running Nagios to check the availability of hosts and services
  might want to use the checkonline method as well - this is why checknagios has
  been invented.

  [ggz-cmd localhost guest guestpassword checknagios]

  The webpage of ggz-cmd is <<http://www.ggzgamingzone.org/backend/cmd/>>.

 Section: The ggzduedit command line utility

  If you want to lookup the registered players, you can do so very easily using
  the [ggzduedit] tool. This allows you to retrieve the passwords of the
  registered players, and to add or delete them manually.
  It is also very helpful for debugging.
  If any user should get admin privileges on the server, then this can be
  adjusted using [ggzduedit] as well.
  Note that this tool expects the same database that ggzd uses. Connection
  parameters for remote SQL servers equal those of popular SQL command line
  tools.
  An example session to such a server is initiated by calling:

  [ggzduedit -H localhost -D ggz -u ggzd -p]

  If not all of the parameters above are given, the standard mode (using a local
  database in libdb format) is entered, unless the ggzd configuration file can be
  read - no parameters need to be given in this case.

  The following permission bits exist within GGZ:

   * PERMS_JOIN_TABLE: Allows the player to join any games. This is normally
  set for all players.
   * PERMS_LAUNCH_TABLE: Allows the player to launch any games. This is also
  normally set for all players.
   * PERMS_ROOMS_LOGIN: The player gets access to rooms which are reserved for
  registered players only. Thus, this flag is normally set for all registered
  players.
   * PERMS_ROOMS_ADMIN: The player gets access to rooms reserved for
  administrators. This is never set by default, but must be explicitely enabled
  to indicate administrator level.
   * PERMS_CHAT_ANNOUNCE: Privilege to broadcast messages to all rooms at
  once. This is never set by default, but could be set for administrators.
   * PERMS_CHAT_BOT: For handles which refer to registered bots. This has no
  privilege implications, it is used solely for information purposes.
   * PERMS_NO_STATS: Players carrying this flag will not be taken into
  account for statistics calculations.
   * PERMS_EDIT_TABLES: Players with host privileges can edit the tables
  of running games. This applies to ordinary hosts and to administrators.
   * PERMS_TABLE_PRIVMSG: Allows to chat while playing a game. This
  applies to ordinary hosts and to administrators.

  Generally, it is recommended to create at least one admin (with both
  PERMS_ROOM_ADMIN and PERMS_CHAT_ANNOUNCE set), a login for the ggz-cmd utility
  (with only PERMS_CHAT_ANNOUNCE set), and a login for the chatbot grubby (with
  PERMS_CHAT_BOT set).

 Section: Network traffic tool: colorsniff

  The [colorsniff] program can be used to track problems if there are
  GGZ connection or communication problems. It is currently available via the
  playground SVN module.
  The tool [ngrep] must be installed to make it work:

  [ngrep -d lo | colorsniff --noping]

  The [--noping] option tells the program to ignore the permanent
  PING/PONG command which are used to measure the player lag.

Chapter: Server Maintainance

 Section: Security

  A game server should, like all other remote services, never be a security risk.
  A few rules should be applied to every installation:

   * Never run ggzd as root, it will refuse to do so anyway. However, when
  started as root it will try to change to the configured user and group first,
  which is normally games.games. Care should be taken about the directory where
  it places its dynamic data - this should ideally be created by the installation
  script.
   * Don't install unnecessary extra servers on the host where ggzd runs. Game
  servers are very often the target of people trying to break into the system,
  and be it because they're frustrated by having lost a game.
   * At a maximum, a full GGZ server needs to have the ports 5688, 5699, 15688
  and 15689 open.
   * Use server-side encryption (hashing) of user passwords if possible.
   * Configure the server so that it support TLS.
   * Use the Interface configuration option to restrict ggzd to a local port.

  Section: Configuration of Transport Layer Security

  To enable TLS, the following entries are available in ggzd.conf:

   * EncryptionUse
   * EncryptionPassword
   * EncryptionKey
   * EncryptionCert

  For anonymous TLS, as done by the GnuTLS variant, setting EncryptionUse to 1 is
  already sufficient. However, when dealing with certificates, the key and
  certificate file must be specified (both might be inside the same PEM file),
  and the password for the key must be given in the clear.

 Section: Privacy

  Everyone hosting GGZ servers can freely decide what policy he uses for player
  data such as passwords or contact email addresses. However, to make thing
  easier for many people, the GGZ Development Team has started to maintain a
  document with some recommandations. This will maybe be part of this document in
  a later edition.

 Section: Technical issues

  From time to time a host running a GGZ server should be checked. The list of
  processes should look normal (barring any zombie ggzd child processes), the
  player database should be intact, and the transmitted network data, consisting
  mostly of the session protocol, chat texts and game data, should be checked for
  flooding or similar.

  A great aid will be to check the server compile-time configuration with the
  option [ggzd --specs], and to check the log messages using
  [ggzd -F --log=all] and using the DumpFile option in ggzd.conf.

  Scalability is another matter of concern for GGZ administrators.
  In the file @file{/etc/security/limits.conf}, the maximum number of
  connections for ggzd can be configured, by adding the following two
  lines and a relogin.

  ggzd   hard    nofile  4096
  ggzd   soft    nofile  4096

 Section: Social issues

  In larger communities, social problems such as griefing players or
  generally misbehaving users occur naturally.
  GGZ cannot prevent this from happening, but the protection against
  this is improving constantly.

  From GGZ 0.0.14 on, the concept of host players was introduced.
  This indicates a privilege level between full administrators and
  ordinary players. Hosts can use chat commands to @emph{gag} players
  or even kick them from the server.

  GGZ Community provides a karma system to support the creation of
  networks of trust.

 Section: Adding rooms

  Games on the GGZ server take place in "rooms" By default, we provide
  you with a single room for each game type, but adding a room couldn't
  be easier.  By default, the ggzd.conf file will specify that the
  server should utilitze _all_ available rooms.  So now the question
  becomes, how do I make a room available?

  In the configuration directory (where you found ggzd.conf and
  ggzd.motd) you will find a subdirectory named 'rooms'.  Inside this
  subdirectory are a number of '*.room' files.  Each .room file
  specifies a different room, and by default each one of them will be
  loaded.

  Again, the sample files are self-explanatory.  To create a new room,
  simply copy one of the existing room files to a new file and edit the
  values as you see fit.

  Administrative action could be necessary for the values of MaxPlayers and
  MaxTables, if the server load gets too high, and EntryRestriction to
  disallow access to the room to guest players or additionally ordinary players,
  taking the values "registered" and "admin", respectively, with "none" being
  the default.

 Section: Adding games

  Currently there are no user-installable game types.  All the games
  that are compliant with GGZ (that we know of) are included with GGZ at
  this time.  However, in the configuration directory, there is a
  'games' subdirectory.  Inside this subdirectory are a number of
  '*.dsc' files.  Each .dsc file specifies a different game type, and by
  default each one of them will be loaded.  This is where you would put
  a new game type if you had (ahem: wrote) one.

  In the future it will be very simple to install a new game module, and
  you can do it without recompiling your server.  Simple put a .dsc file
  in the aforementioned 'games' dir describing the game, and then put
  the server module in the appropriate directory (usually (prefix)/lib/ggzd).

 Section: Log files

  You will no doubt want to log your GGZ server's activity.  Setting up
  logging, and the details to log, to a file is almost completely
  self-explanatory in the ggzd.conf file.  Setting up logging via the
  syslog facility may be less than obvious.

  Logging via syslogd is the default unless you specify a log file
  (either in ggzd.conf or on the command line).  By default, log entries
  from the GGZ server will go to the facility local0.  This can be
  specified in ggzd.conf.

  You will however, need to setup your /etc/syslog.conf file to log those
  messages from facility local0 (or whatever you choose) into a specific
  file, probably /var/log/ggzd.

  If you compiled the GGZ server with debugging enabled, it will
  generate extra information which you may want to go to a separate
  file.  If you are are not using syslog then this is configurable in
  ggzd.conf.  If you *are* using syslog, here is a convenient set of
  syslog.conf entries to separate debug messages from standard log
  messages:

  local0.info /var/log/ggzd.log
  local0.=debug /var/log/ggzd.debug

  Put those two lines into your syslog.conf, restart syslogd and your log
  nightmares are over.

  To test a server's communication with a single client, the DumpFile variable
  can be filled with either a file name or a virtual file name such as stderr.

Appendix: Local GGZ server installation

  These instructions apply to a vanilla 0.0.14 installation if one doesn't have
  system privileges.
  You may have to modify some details though.
  Note that the [getggz.sh] script or [ggzbuild] usually handle
  many of the steps below.

  <<http://ftp.ggzgamingzone.org/pub/contrib/getggz.sh>>

  cd ~
  mkdir ggz-0.0.14
  cd ggz-0.0.14
  svn co svn://svn.ggzgamingzone.org/svn/tags/ggz-0-0-14/libggz
  svn co svn://svn.ggzgamingzone.org/svn/tags/ggz-0-0-14/ggzd
  svn co svn://svn.ggzgamingzone.org/svn/tags/ggz-0-0-14/python
  export LD_LIBRARY_PATH="$HOME/localsys/usr/lib:$LD_LIBRARY_PATH"
  export PATH="$HOME/localsys/usr/bin:$PATH"
  cd libggz
  ./autogen.sh --prefix=$HOME/localsys/usr
  make
  make install
  cd ..
  cd ggzd
  ./autogen.sh --prefix=$HOME/localsys/usr
  make
  make install
  cd ..
  cd python
  ./autogen.sh --prefix=$HOME/localsys/usr
  make
  make install
  cd ..
  ggzd -F

Appendix: Known GGZ servers and Contact

  The following servers are known to run permanently. For an up-to-date list,
  please consult the GGZ meta server, using one of the available client-side
  tools.

   * <<ggz://live.ggzgamingzone.org>>
  (France, fast connection, operated by GGZ developers)
   * <<ggz://ggz.openladders.net>>
  (USA, fast connection, operated by OpenLadders Partnership)

  The GGZ Community is a web-based portal which emerged from the former
  GGZ Rankings pages. It also contains the Java applet for playing GGZ games
  via the browser.

  <<http://www.ggzcommunity.org/>>

  There are so far no known web pages or similar efforts. For more information,
  don't forget to check the GGZ home page regularly:

  <<http://www.ggzgamingzone.org/>>

  Server hosters are encouraged to subscribe to the ggz-servers mailing list.
  New servers are announced there, as are updates and hosting problems.
  This is a low traffic mailing list.

  <<http://mail.ggzgamingzone.org/cgi-bin/mailman/listinfo/ggz-servers>>

  Subscribing to ggz-announce additionally is always recommeded, too.
  This is a very low-traffic list which almost exclusively focuses on release
  announcements for new versions of GGZ.


