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

  Author: GGZ Development Team

  Copyright (C) 2001, 2002 Josef Spillner
  Published under the GNU Free Documentation License.

  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://ggz.sourceforge.net/docs/ 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 Maintaining:: Help for administrators

Chapter: Foreword

  Over the last months 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.

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

  This describes a typical setup for GGZ 0.0.6.
  All following versions will certainly 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.
   * Network connectivity is present.
   * Libraries and development packages (including headers) are installed
  according to the requirements given in the release information; at present,
  this is:

   * libdb 2 or 3, optionally mysql or postgresql
   * libpopt
   * libexpat
   * perl

 Section: Hardware requirements

  You should calculate a need of about 10-20 MB of initial disk space, which
  might however not be enough if the server runs over a long time.
  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 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

  Before the main server (ggzd) can be installed, its dependencies must be
  resolved. The GGZ package 'libggz' is currently the questioned
  package; this replaces the 'easysock' package which was used in version 0.0.4.
  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 'libggzdmod' as well.
  When installing from source, all of those can be found in the 'ggzd' CVS
  module.
  Upon installation, lots of files and directories are created under the
  chosen prefix (usually /usr/local when installing from source and /usr
  otherwise):

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

  The prefix can be changed when running
  [configure --prefix=/usr/local/ggz], for example.
  Likewise, [--sysconfdir] may be used to specify the location for
  configuration files, and [--with-tmpdir] points to where temporary
  socket files are created.

  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.
  For installations from source, the getggz.sh script is recommended, because it
  handles this task very fast in an interactive way.
  This script, together with several others, will eventually be part of a server
  support package.
  For the time being, it is present in Appendix A.

  The database type can also be chosen freely. See the next chapter for details.

  Section: Message of the day

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

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

  You can use premade MOTDs which are available from the motds directory of the
  GGZ utils CVS module.

  Section: Widely used terms

  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.

  Section: 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.

 Section: Normal installation

  A ggzd alone is not much fun, there are other components as well which are
  worth to be installed:

   * The GGZ Meta Server
   * 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.

  Have a look at the next chapter on how to set up GGZ with enhanced database
  support.

Chapter: Databases

 Section: Database choices

  The GGZ server is able to store its data in various database formats.
  Currently, not only the traditional libdb format is supported (db2 and db3),
  but also 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.

 Section: Berkeley DB setup

  When using libdb3, nothing special has to be done. For libdb2 support,
  running configure with [--with-database=db2] when installing from
  source is sufficient. The server cares about creating and managing the
  database.

  Sometimes the wrong libdb type is chosen, which prevents users from creating
  accounts and more. Forcing [--with-database=db3] might fix this.

 Section: SQL setup

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

   * DatabaseHost
   * DatabaseName
   * DatabaseUsername
   * DatabasePassword

 Section: MySQL setup

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

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

 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 'ggzd';
  		CREATE DATABASE ggz OWNER ggzd;

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

  		psql template1
  		CREATE USER ggzd;
  		CREATE DATABASE ggz;
  		\q
  		psql ggz
  		CREATE TABLE users (
  			id serial NOT NULL,
  			handle varchar(256) NOT NULL,
  			password varchar(256),
  			name varchar(256),
  			email varchar(256),
  			lastlogin int8,
  			permissions int8
  		);
  		GRANT ALL ON users TO ggzd;
  		GRANT ALL ON users_id_seq TO ggzd;

  You can speed up the table with an index, like:

  		CREATE index xhandle ON users (handle);

  Make sure the connection can be established. When the database is running on a
  remote server, it must accept internet connections (startup option -i), and
  allow the remote access, which could be granted using the following entry in
  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.

 Section: Format

  The database format is the same for every configuration.

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

Chapter: Internal Games

 Section: 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. In the future this
  will include game statistics, rankings, saved games 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.

  Each game has its homepage on:

  <<http://ggz.sourceforge.net/games/<gamename>>>

 Section: Server-side game storage

  From release 0.0.6 on, each game stores 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.

 Section: Overview on the games

  Section: Kamikaze

  This game server is not part of GGZ yet, but will be from version 0.0.7 on.

  Section: Chess

  This is the GGZ variant of the chessd server, which is developed using the
  cgc library from <<http://chessd.sourceforge.net>>, like the chessd Fischer
  server.

  Section: Chinese Checkers

  A chinese checkers game for 2-6 players.

  Section: Combat

  This is the server for the strategy game Combat.

  Section: Copenhagen

  The Copenhagen server was not part of GGZ 0.0.5 because it was not stable enough.
  You can however install it from source, which is available from MindX CVS:
  <<http://mindx.sourceforge.net>>

  Section: Dots

  A Connect the Dots server for GGZ.

  Section: Escape

  The escape server serves the Windows game client Escape, see
  <<http://wggz.sourceforge.net>> for details.

  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.

  Section: Hastings1066

  Strategy game for 2-8 players.

  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.

  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.

  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.

  Section: Reversi

  Game server for the reversi game.

  Section: TicTacToe

  The easiest game, which does therefore serve as an example for beginners in GGZ
  game development.

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 'external games'. Their installation base is varying, although
  it is not very difficult to support these games as well. All major GGZ servers
  should include all of them to give their players a better choice.

 Section: Availability

  See <<http://ggz.sourceforge.net/sections.php?op=viewarticle&artid=12>> to
  view the list of external games. There are already patched convenience tarballs
  available at:

  <<http://teg.sf.net/teg-0.9.3-ggz.tar.gz>>
  (Note: The current version 0.10.1 has GGZ support included.)

  <<http://teg.sf.net/gbatnav-1.0.4pre.tar.gz>>
  (Note: The current version 1.0.4 has GGZ support included.)

  <<http://teg.sf.net/xtux-ggz.tar.gz>>

  <<http://teg.sf.net/freeciv-1.12.0-ggz.tar.bz2>>

 Section: Description of available external games

  Section: Batalla Naval

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

  Section: bzFlag

  The server for the well-known realtime 3D tank game. This server is a patched
  version of bzFlag, which is available from <<http://www.bzflag.org>>.
  Note that bzFlag support is work in progress.

  Section: Freeciv

  A patched version of the FreeCiv server (<<http://www.freeciv.org>>) runs
  over GGZ as well.
  A possible configuration is:

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

  Section: Stalker

  Stalker is an SDL realtime game which uses UDP communication.
  See <<http://stalker.sourceforge.net>>.

  Section: T.E.G.

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

  Section: XTux

  XTux is also available with GGZ support.
  However, it is not configured using GNU autotools, so you will have to adjust
  all the paths by yourself if necessary. This includes the directory src/ggz and
  src/server.
  <<http://xtux.sourceforge.net>>

Chapter: Other GGZ Servers

 Section: The GGZ Meta Server (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. Meta servers
  operate in networks and keep themselves consistant automatically, so that both
  a broken GGZ server and a broken GGZ Meta Server 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 current implementation of the GGZ Meta Server is read-only, so the
  configuration file needs to be maintained by hand.
  It runs on port 15689.
  You can get ggzmetaserv as part of the GGZ utils package.

 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 inetd on port 15688. This allows to connect to
  any GGZ server from all over the world, whereever one finds a telnet client.

 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.

Chapter: GGZ Server Tools

 Section: The ggz-cmd command line utily

  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 utily ggz-cmd can be used.
  It is available from the utils/cmd-client directory.

  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]

 Section: The ggzduedit command line utily

  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.

 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 CVS 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 Maintaining

 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, 15688 and
  15689 open.

 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.

 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.

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

Appendix: Local GGZ server installation

  These instructions apply to a vanilla 0.0.6 installation if one doesn't have
  system privileges.
  You may have to modify some details though.

  cd ~
  mkdir localsys
  mkdir localsys/usr
  mkdir localsys/etc
  mkdir ggz-0.0.6
  cd ggz-0.0.6
  export CVSROOT=:pserver:anonymous \
  	@cvs.ggz.sourceforge.net:/cvsroot/ggz
  cvs login
  cvs -z3 co -rggz-0-0-6 libggz ggzd
  cd libggz
  ./autogen.sh --prefix=$HOME/localsys/usr
  make
  make install
  cd ..
  cd ggzd
  export LD_RUN_PATH=$HOME/localsys/usr/lib
  export LD_LIBRARY_PATH=$LD_RUN_PATH
  ./autogen.sh --prefix=$HOME/localsys/usr \
  	--with-database=db3 --with-libggz-dir=$HOME/localsys/usr
  make
  make install
  cd ..
  export PATH="$HOME/localsys/usr:$PATH"
  ggzd

Appendix: Known GGZ servers and Contact

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

   * <<ggz://jzaun.com>> (USA, developers, medium connection)
   * <<ggz://ggz.snafu.de>> (Germany, fast connection)
   * <<ggz://ggz.morat.net>> (USA, fast connection) (Currently not available)
   * <<ggz://ggz.homeip.net>> (Argentina, medium connection)
   * <<ggz://mindx.dyndns.org>> (Germany, medium connection)

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

  <<http://ggz.sourceforge.net>>

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

  <<http://lists.sourceforge.net/lists/listinfo/ggz-servers>>


