[Top] [Contents] [Index] [ ? ]


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1. 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2. 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3. Installation

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1 The impact of a GGZ installation

In the old days, installing GGZ meant installing the 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3 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:

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5 Base installation

This rather large section covers the minimum software installation and configuration to get a GGZ server going. This includes the libggz and 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 libggz is currently the first such package; this replaces the 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 ggzd, which is the main server, and ggz-game-servers including many game servers, should follow. Both need the library package ggzdmod and its C++ wrapper ggzdmod++ as well. When installing from source, all of those can be found in the ggzd SVN module which gets packaged under the name ggz-server. In addition, the ggz-python package provides the pyggzdmod wrapper library and a couple of game servers on top of it, so its installation is recommended as well.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.1 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.2 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 ‘/usr’ and ‘/usr/local’. If this is not the case, GGZ dependencies can be forced to be found by adding --with-ggz-dir=DIR to the ‘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 ‘/usr’ or ‘/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 ‘/usr/local’ when installing from source and ‘/usr’ otherwise), assuming the paths were not customized when calling the ‘configure’ script:

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.3 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 ‘etc/ggzd/ggzd.motd’. Its path is configured in ‘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:

You can use premade MOTDs which are available from the ‘motds’ directory of the ggz-utils package. In addition, the 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. The text MOTD has a limit of 80 lines which can be changed through MAX_MOTD_LINES at compilation time.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.4 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 server provides different 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 game type. Based on these types, players start to play their games by creating 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 lounge, but it might also apply to some rooms reserved for server administrators.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.5 Main GGZ server configuration

The main GGZ server (ggzd) is configured by a single file, named ‘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 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5.6 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.6 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:

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.7 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 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 ‘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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4. Databases

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1 Database choices

The GGZ server is able to store its data in various database formats. Currently, not only the traditional Berkeley DB format is supported (called 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.

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 ggz-community package contains all the necessary SQL schema files in the directory setup/sql.

GGZ Community uses PostgreSQL or MySQL, if in doubt these databases should be used. Some of its functionality depends on advanced database features such as stored procedures, triggers and notifications which work best with PostgreSQL.

Database functionality is loaded into the GGZ server as plugins. Therefore, multiple database backends can be compiled with a command like ./configure --with-database=db4,pgsql. The first such backend will be loaded as the default plugin. This can be overridden by changing the setting DatabaseType in ‘ggzd.conf’. When the first or only such backend is DBI, the selection of DatabaseType is mandatory.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2 Embedded databases setup

When using DB4 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.

The DB4 databases are stored in ggzd’s writeable statedir (usually ‘/var/lib/ggzd’). No further configuration in ‘ggzd.conf’ is necessary, although the setting DatabaseName can be set to the special value memory for DB4 to run the server with volatile databases which are not stored on disk.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3 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.

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:

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3.1 MySQL configuration

If ggzd uses MySQL as its database, most of the necessary 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 (user/database creation) followed by the fifth entry (extended privileges) 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 ‘my.cnf’ must be disabled.

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3.2 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

Once the database is created, its tables must be set up. Starting from GGZ 0.0.15pre, the PostgreSQL database backend will do this automatically. It will read the SQL schema file installed in ggzd’s data directory and execute all of its statements.

One of the created tables is the control table. The control table is used internally by ggzd to detect upgrades.

You can speed up the user 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 ‘data/pg_hba.conf’:

	host ggz 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 ggz-community package should be used eventually.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.4 Format of the database tables

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. Have a look at the next section to learn about compatibility issues.

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.5 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.

Sometimes, the database schema of the GGZ is changing. Likewise, new versions of the database software sometimes introduce on-disk format changes. For DB4, performing such upgrades is outside the scope of the GGZ server. Instead, the utilities which are part of the software should be used, for example to upgrade from DB 4.5 to DB 4.6: db4.5_upgrade; db4.6_upgrade

If the GGZ schema changes, the server will detect a version number mismatch and abort. In the future, upgrade scripts might be provided. In the meantime, a manual modification of the tables is required.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.6 Integration and synchronization

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.6.1 GGZ Community

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 ‘setup/sql/trigger’ within the GGZ Community sources.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.6.2 Internationalisation

The GGZ server is eager to please all the needs of international player crowds. Unicode support includes the stringprep functionality which can be considered a superset of casefolding for the purpose of comparing strings. The PostgreSQL database will attempt to detect the stringprep stored function on startup and use it if available. It is not installed by default. In order to have it installed, go to the directory ‘database/proc’ within the GGZ server sources, and call make. For installation requirements, have a look at the enclosed README file.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5. Internal Games

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.1 Scope

We call all the games which come along with GGZ 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 internal game servers are included in the ggzd SVN module of GGZ in the ‘game_servers’ directory. Alternatively, binary packages named 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:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.2 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. ‘/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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.3 Other game features

In addition to savegames, some games support 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 ggz-docs package, and on the beforementioned game server homepages.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4 Overview on the games

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.1 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 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 named bots feature.

The chess server can save games in the PGN format.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.2 Chinese Checkers

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.3 Chinese Chess

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.4 Combat

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.5 Connect the Dots

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.6 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.7 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.8 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. 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.9 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.10 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.

Keepalive is now available only through GGZ’s graveyard. Information is available on http://dev.ggzgamingzone.org/graveyard/.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.11 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.13 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.14 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.

NetSpades is now available only through GGZ’s graveyard. Information is available on http://dev.ggzgamingzone.org/graveyard/.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.15 Reversi

Game server for the reversi game.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.16 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.17 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.18 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).

Tuxman is now available only through GGZ’s graveyard. Information is available on http://dev.ggzgamingzone.org/graveyard/.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.19 Checkers

The Checkers game is sometimes referred to as Draughts.

It is not part of the ggz-server package, but of ggz-python instead.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.20 Hnefatafl

Hnefatafl is an old nordic game.

It is not part of the ggz-server package, but of ggz-python instead.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.21 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.22 Ludo

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

It is not part of the ggz-server package, but of ggz-python instead.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.23 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 ‘playground/server/games’.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6. External Games

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.1 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 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.2 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3 Description of available external games

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3.2 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.

Batalla Naval does not seem to be maintained anymore.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3.3 Freeciv

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

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3.4 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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3.5 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3.6 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3.7 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3.8 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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3.9 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7. Other GGZ Servers

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.1 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 the metaserver is http://www.ggzgamingzone.org/backend/metaserver/.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.2 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 telggz is http://www.ggzgamingzone.org/clients/telnet/.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.4 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8. GGZ Server Tools

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.1 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 ‘utils/cmd-client’ directory, or as part of a 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/.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.2 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:

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). Using the simplified privilege roles, that would be one admin user and two bot users.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.3 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9. Server Maintainance

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.1 Security

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.1.1 Configuration of Transport Layer Security

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

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.1.2 Policies for registration and login

Starting in GGZ 0.0.15pre, it is possible to control whether users are allowed to register at all and which characters the usernames can contain. Note that the latter settings also affect guest names!

The RegistrationPolicy configuration option can be set to ’closed’ to prohibit new registrations. Administrators can still add players by running the ggzduedit command. The default policy is ’open’. The advanced policy ’confirm’ allows the registration of accounts, but doesn’t allow their use until an account is being confirmed. The fourth policy, ’confirmlater’, works like ’open’ but requires a timely confirmation to prevent the account from being erased. How and when confirmation takes place is currently outside of scope for ggzd. Instead, the use of GGZ Community is required which sends out email to let players confirm their email address.

The UsernamePolicy setting points to a file which contains a detailed configuration of what character sets are allowed. If not given, all characters can be used in usernames. Even if given, ggzd must be compiled with support for the ICU library to take it into account.

An additional compiled-in library will effect the registration process: If either cracklib or omnicracklib have been enabled, passwords are checked for their strength when registering. Some tools like omnicrackdict might have to be used to set up effective databases of words to match against. Again, password strength checking profits from the ICU library, if omnicracklib has been compiled with it and is used by ggzd.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.2 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.3 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 ‘/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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.4 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 gag players or even kick them from the server.

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.5 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.6 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).

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.7 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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

A. 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.


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 install
cd ..
cd ggzd
./autogen.sh --prefix=$HOME/localsys/usr
make install
cd ..
cd python
./autogen.sh --prefix=$HOME/localsys/usr
make install
cd ..
ggzd -F

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

B. 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.

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.


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


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.


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.

[Top] [Contents] [Index] [ ? ]

Table of Contents

[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated by Josef Spillner on August 1, 2010 using texi2html 1.82.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ < ] Back Previous section in reading order 1.2.2
[ > ] Forward Next section in reading order 1.2.4
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ Up ] Up Up section 1.2
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

This document was generated by Josef Spillner on August 1, 2010 using texi2html 1.82.