/ 
Frivolity-0.7.1
/ volityd

NAME

volityd -- A daemon that runs a Volity parlor or bot factory

DESCRIPTION

This is a program for running Volity servers, including parlors and bot fatcories. Run with valid configuration options, it acts a noninteractive daemon that either hosts a Volity game or makes available a bunch of bots for other Volity games to use.

CONFIGURATION

You can run volityd with a configuration file, or by supplying a list of command-line options at runtime. You can also mix the two methods, in which case options you specify on the command line will override any of their counterparts in the config file. See "Config file format" for more about the config file.

Since there are many options, we recommend the use of a config file. The examples/ directory included with this distribution contains one config file for running a Tic Tac Toe parlor, and another that runs a Tic Tac Toe bot factory.

In the following documentation, each option has two names listed: its one-letter abbreviation followed by its long name. Either is usable on the command line, but the config file works with the only the long names.

For example, to set the Jabber ID that your server should use as foo@example.com, you can either supply -J foo@example.com or -jabber_id=foo@example.com on the command line, or the line jabber_id: foo@example.com in the config file.

An exception comes in how you define bots; see "Configuring bots".

Required parameters

The program will immediately die (with a specific complaint) if you don't specify enough information on the command line to allow the parlor or factory to authenticate with the Jabber server, or run a game module. Use an appropriate combination of the following flags to achieve this.

h host

The hostname of the Jabber server that the parlor or factory will use.

If this is not defined but jid_host is, then this will be set to the value of jid_host.

s jid_host

The hostname that the parlor or factory will use in its own Jabber ID.

By default, this will be the same as the value of host. You usually won't need to set this unless you are connecting to the jabber server via proxy, and the name of the host you are connecting to is different than the host part of your parlor or factory's intended JID.

u username

The Jabber username that the parlor or factory will use when connecting.

p password

The password that the parlor or factory will use when authenticating with the Jabber server.

If you supply this on the command line, volityd will automatically modify $0 so that it won't be exposed to process-listing commands like ps.

g game_class

The full Perl package name of the game module that the parlor or factory will run. It must be visible to @INC.

J jabber_id

The parlor or factory's full Jabber ID. You can use this flag instead of using the username, jid_host and resource options. (But you can't use both this and them.)

L ruleset_uri

Bot factories only. If you are running a volityd process as a bot factory, then you must specify the URI of the Volity ruleset that you will provide bots for.

If you're running this program as a parlor, you don't need to specify this, since your Volity::Game subclass already should define its ruleset.

Optional parameters

Each of the following are optional. Not defining them at runtime will result in default behavior as described.

a admins

A comma-separated list of Jabber IDs that are allowed to send admin.* RPCs to this parlor or factory. All admin.* calls from Jabber IDs not on this list result in faults sent back to the caller.

Default: None.

b bookkeeper

The JabberID of the Volity network's bookkeeper.

Default: bookkeeper@volity.net/volity

c contact_email

The contact email address of the person responsible for this parlor or factory.

Polite servers set either this or the contact_jabber_id option (or both).

Default: None.

f pidfile

The filesystem pathname of the pidfile to be created when the server starts.

Default: None, and no pidfile is used.

i log_config_info

A string containing Log::Log4perl configuration information, defining the behavior of the volityd logger. See Log::Log4perl. (A reference to this string is passed directly to that module's init() method.)

The logger works through various Log4perl invocations already spread throughout the Volity modules, set at appropriate priority levels, ranging from 'DEBUG' to 'INFO' to 'FATAL'.

The program will die with an error if you define both this option and log_config_file.

Default: None, and no logging occurs unless you specify a value for the log_config_file option.

j contact_jabber_id

The contact Jabber ID of the person responsible for this server.

Polite servers set either this or the contact_email option (or both).

Default: None.

m muc_server

The hostname of the Jabber MUC server to use when creating new game tables.

Default: conference.volity.net

o port

The Jabber server's TCP port.

Default: 5222 (the standard Jabber connection port)

r resource

The Jabber resource string that the server will use after authenticating. The string 'volity' (the default string) is a good choice for 'live' servers; use something like 'testing' otherwise.

Default: 'volity'

v volity_version

The version number of the Volity platform protocol that this server supports.

Unless you're doing something highly unusual with the Volity Perl libraries, you're probably best sticking with the default value on this one.

Default: 1.0

C config

The path to a volityd config file. See "Config file format".

If you specify any command-line options beyond this one, they will override any config options specified in the file.

Default: None, and volityd will look for all options to come from the command line.

F log_config_file

The filesystem pathname of a Log::Log4perl configuration file, which defines the behavior of the volityd logger. See Log::Log4perl. (The filename is passed directly to that module's init() method.)

The logger works through various Log4perl invocations already spread throughout the Volity modules, set at appropriate priority levels, ranging from 'DEBUG' to 'INFO' to 'FATAL'.

The program will die with an error if you define both this option and log_config_info.

Default: None, and no logging occurs, unless you specify a value for the log_config_info option.

R role

The role that this server will play on the Volity network. There are only two legal values for this option: parlor and factory.

Default: parlor

V visibility

Whether or not this server is visble to Volity's game finder. Set to 1 if it is, or 0 if it should go unlisted.

Default: 1

Config file format

If you specify a config file via the -C or --config command-line options, then you must prepare a YAML file at that location. Its contents are simply a list of the options you want to set, with one option per line (but see "Configuring bots" for an exception). Each option is keyed by its long name. Here's a possible snippet:

username: foo
host: volity.net
password: secretpassword42
game: Volity::Game::MyFunGame

To specify a multiline value, set the value after the colon to | (a pipe character), followed by a newline, and then the value with every line indented, like so:

log_config_info: |
 [ line 1 of config info ]
 [ line 2 of config info ]
 [ ... ]

For more information about the YAML markup format, see YAML or http://yaml.org .

Configuring bots

You can configure your server to know about Perl-based Volity bot classes (subclasses of Volity::Bot) that are installed on your machine. This is a requirement for bot factories (whose existence isn't very meaningful without them), and it's not required but recommended for parlors. A parlor that knows about local bot classes will make those bots available to its players without having to go through external bot factories.

You must specify several parameters for each bot class to use. These include the name of the bot's Perl class, a Jabber ID, and a password. (This latter is not necessary for bots whose basic Jabber ID matches that of your parlor.)

Because of the plurality of options involved, bot configuration from the command line works differently than from a config file.

The relevant command line options include:

B bot_class
U bot_username
H bot_host (Defaults to value of bot_jid_host.)
S bot_jid_host (Defaults to value of bot_host.)
I bot_jabber_id (You can use this instead of bot_user & bot_jid_host.)
P bot_password (Not necessary if the bot and the parlor share a JID.)

To define multiple bots, just invoke the flags multiple times. For example:

$ volityd -C some_config.yml -bot_class=Volity::Bot::MyFirstBot\
                             -bot_jabber_id=firstbot@volity.net\
                             -password=secretPASSword\
                             -bot_class=Volity::Bot::MyOtherBot\
                             -bot_jabber_id=secondbot@volity.net\
                             -password=SECRETpassWORD

From the config file, define instead a YAML sequence under the key "bots". Each member of the sequence is a YAML mapping with the following keys:

class
username
host (Defaults to value of jid_host.)
jid_host (Defaults to value of host.)
jabber_id (You can use this instead of username and jid_host.)
password (Not necessary if the bot and the parlor have the same JID.)

Here is an example config file snippet that performs the same bot configuration as above:

 bots:
	 - bot_class:     Volity::Bot::MyFirstBot
	   bot_jabber_id: firstbot@volity.net
           password:      secretPASSword
	 - bot_class:     Volity::Bot::MyOtherBot
	   bot_jabber_id: secondbot@volity.net
           password:      SECRETpassWORD

SEE ALSO

AUTHOR

Jason McIntosh <jmac@jmac.org>

COPYRIGHT

Copyright (c) 2006 by Jason McIntosh.