***** The GGZ Gaming Zone 0.99.3 - Hosting Guide *****
*** Instructions and Recommendations for Server Hosters ***
Author: GGZ Development Team
Copyright (C) 2001 - 2008 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 number
* %t: local time on the server
* %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.
The text MOTD has a limit of 80 lines which can be changed through
MAX_MOTD_LINES at compilation time.
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 <>, 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 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 @b{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 @file{ggzd.conf}. When the first or only such backend is DBI,
the selection of DatabaseType is mandatory.
Section: 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
@file{/var/lib/ggzd}). No further configuration in @file{ggzd.conf} is necessary,
although the setting DatabaseName can be set to the special value @b{memory}
for DB4 to run the server with volatile databases which are not stored on disk.
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.
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, 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 @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';
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
@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 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.
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.
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.
Section: Integration and synchronization
Section: 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 @file{setup/sql/trigger}
within the GGZ Community sources.
Section: 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 @file{database/proc} within the
GGZ server sources, and call [make]. For installation requirements,
have a look at the enclosed README file.
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:
<>>
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/}.
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 <>, 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
<> 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 <>.
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.
Keepalive is now available only through GGZ's graveyard. Information is
available on <>.
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 <>.
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.
NetSpades is now available only through GGZ's graveyard. Information is
available on <>.
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 <>.
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 <>.
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 <> 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 <>.
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 <>.
@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}
<>
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.
<>
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.
<>
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.
<>
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.
<>
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.
<>
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 the metaserver is <>.
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 telggz is <>.
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 <>.
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
<>.
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 <>.
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). Using the simplified privilege roles, that would be one
admin user and two bot users.
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: 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.
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.
<>
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.
* <>
(France, fast connection, operated by GGZ developers)
* <>
(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.
<>
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.