/ 
Frivolity-0.6.3
/ volityd

NAME

volityd -- A daemon that runs a Volity parlor

DESCRIPTION

This is a program for running Volity parlors. It uses the Volity hierarchy of Perl modules to run a game module specified at runtime.

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 a config file for running a Tic Tac Toe parlor.

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 parlor 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 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 will use.

u username

The Jabber username that the parlor will use when connecting.

p password

The password that the parlor 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 will run. It must be visible to @INC.

J jabber_id

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

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

Polite parlors 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 parlor 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 parlor.

Polite parlors 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 parlor will use after authenticating. The string 'volity' (the default string) is a good choice for 'live' parlors; use something like 'testing' otherwise.

Default: 'volity'

v volity_version

The version number of the Volity platform protocol that this parlor 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.

V visibility

Whether or not this parlor 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

If you'd like your parlor to be able to use Perl bot classes installed on your machine (i.e. subclasses of Volity::Bot), then you must specify several parameters for each 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
I bot_jabber_id (You can use this instead of bot_user & bot_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
jabber_id (You can use this instead of user & 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.