Grubby Administration Manual

Revision: 0.6
Date: 28.12.2005
Author: Josef Spillner <josef at ggzgamingzone dot org>

This documentation is geared towards the configuration of grubby and basic understanding of its structure. For further reading, the Grubby User Manual and the Grubby Architecture Manual are available.

Installation

Grubby consists of the binary "grubby", the perl script "grubby-config", and many plugins (shared libraries). There are two groups of plugins: core modules, of which only one can be active at a time (to be determined at program startup), and normal modules, of which none to all can be loaded, and even unloaded and reloaded at runtime. Additionally, some scripts are available to be executed with either the embed or exec module, and then some data files and translated message catalogs. Everything should install fine.

All you have to do then is to call grubby-config, which gives you a full default installation. You might want to cut the options down, just edit the configuration files under $HOME/.ggz/grubby.rc. Then launch the bot while having a ggzd or IRC server running somewhere. If it fails, make sure you didn't cut too much options. Use netconsole.so as net core module to test for errors not relating to network protocols. Read docs/Setup for a full sample file, a short overview follows.

This is a minimal configuration file. By default it is expected to reside in $HOME/.ggz/grubby.rc. Entries which start with a hash mark (#) are optional.

[preferences]
name = Grubby # Bot name
#password = XXX # Password for registered grubby names
language = en # Bot default language
autojoin = 0  # Channel/room to join after login
owner = you   # Owner nickname
host = localhost # Where to connect to
#logfile = /tmp/guruchatlog
#adminlevel = owner # Owner is the default; can be admin/registered/all too

[guru]
net = /path/to/libguru_netggz.so # or netsilc.so, netirc.so, netconsole.so
player = /path/to/libguru_player.so
i18n = /path/to/libguru_i18n.so
#modules = self people ...

[modules]
self = /path/to/libgurumod_self.so
#...

Network setup

Grubby can communicate with users either locally (for debugging) or being logged into a GGZ, IRC or SILC server. The core module net can be configured appropriately:

For autojoining a room upon login, a number or room name must be given for GGZ (e.g. 0 or tictactoe), while IRC expects a channel with hash mark (e.g. #ggz), and SILC expects a channel without hash mark (e.g. testroom). The implementation netggz.so does not only provide chat, but also gaming features, which are ignored by the other implementations.

Administrative commands

The owner of grubby, as specified in the configuration, may issue some more commands than the other players. Here's a list of what the owner can do in relation to the loadable modules:

The reload command ensures that the latest version of a module is in memory. In addition, the following administrative commands are available: The latter group of commands is available only to the owner by default. By using the adminlevel configuration directive, this can be relaxed to all registered GGZ administrators or regular players, or even to everyone. This directive hence only works with the GGZ network module.

Log files

Grubby can be requested to log all communication to a log file. Also, the player database at ~/.ggz/grubby/playerdb is filled with entries when players join the room Grubby is in. These entries can be enhanced by the players with additional information using the player core module.

Modules

Some of the available modules are documented here.

Exec module

This plugin executes external scripts and programs, writes to their stdin and reads from their stdout. It should be noted that the more external processes are spawned in serial order, the more time it consumes, and grubby may not react fast enough. Whereever available, execution via the embed module or even a native plugin (shared library) should be preferred.

The configuration of the exec module happens through the file $HOME/.ggz/grubby/modexec.rc.

[programs]
programs = translate
translate = /usr/bin/mytranslator --mode=grubby

Embed module

Similar to exec, save it embeds the scripts directly. This works for Python, Perl, Ruby and Tcl so far and requires that support for those languages has been enabled at compile time. One advantage is that all commands are executed much faster.

The configuration of the embed module happens through the file $HOME/.ggz/grubby/modembed.rc, similar to the exec module, but with the identifier being scripts instead of programs.

[scripts]
scripts = test
test = /tmp/test.tcl

Games module

Grubby has the ability to launch game clients which have no GUI when commanded to do so. Those games are registered like normal GGZ game clients, except that their frontend is set to 'guru'.

Scripts for the exec/embed modules

The following scripts are distributed along with grubby (but others can easily be added). The corresponding interpreters should be installed to use them in exec, or the embedded interpreter support should be compiled in to use them in the embed module.

News module script (rdf.pl)

Several news sites offer RDF files which contain all headlines and links to the articles in XML format. Now when the user requests news from one of those sites, the module first fetches the latest RDF file from the target host (needs the perl module Net::Telnet installed), and randomly seeks one of the headlines which is to be returned.

Dictionary module script (dict.pl)

This module is presentated by the perl script "dict.pl", which in turn needs several dictionaries installed, or at least one of them. Under Unix, those are mostly under /usr/share/trans/X-Y, where X and Y are lowercase language letters, like "en" for English. The dictionary files contain key:value pairs of words. Now when a search is done, the module simply opens the appropriate file and scans it. In the case of inverse search, key and value are swapped. The module returns a concatenated string which contains all translations it found for the key word.

Meeting module script (meeting.rb)

This one needs Ruby installed, preferably version 1.6+. Its configurable database goes normally to $HOME/.ggz/grubby/meeting, similar to others. It uses an interesting technique to store its data: Instead of writing key-value pairs, it dumps the whole object so one can transfer it from one host to another.

Translation module script (webtranslator.sh)

In case common shell tools (cut, grep, ...) and wget are available, the script webtranslator.sh can be used for translations. It stores translated pairs of sentences into its cache (~/.ggz/grubby/google).