Vertebra is a distributed application platform running atop the ejabberd XMPP
server.

=== Starting Herault

Agents require an instance of Herault, the discovery and security agent. A very
basic version of Herault ships with this library. Simply start an agent with
the provided config file after editing it to meet your satisfaction.  Note that
you should not configure a herault_jid for the Herault agent (leave it false).
This will change in the future (at which point your config MUST be updated to
maintain security), so please watch out for that.

 $ bin/vagent start -c config/herault.yml

== Running some agents

A 'server' agent (one that will load actors and respond to operations)
requires at least one actor to work. The default defined in the sample slice
agent config is the 'gem' actor for manipulating gems on a host. It also
requires 'default' resources which are usually something about the location
of the agent. The sample uses slice 0 on cluster rd00.

To run the slice agent:

 $ bin/vagent start -c spec/config/slice_agent.yml

To set various paths for pid files, logs and the herault agent's JID, check
the sample config at spec/config/slice_agent.yml. Packet debugging to the log
is switched on with the jabber_debug option.

=== Vertebra Clients -- vshell

There are two approaches.  The first is to start a persistent client agent
which will be controlled via 'vshell'.  To do this, use:`

 $ bin/vagent start -c spec/config/client.yml

You control a client agent via DRb, Ruby's built-in message passing protocol.
The following command drops you into a normal Ruby shell with an instance
variable representing the agent:

 $ bin/vshell <port>

The port number is optional. The default is 10392, the port defined in the
client.yml example.

To send an operation to a JID and wait for its results, use request:

 > @agent.request('/gem/list', :direct, {}, ['rd00-s00000@localhost'])

To perform a single operation over a set of resources which includes
discovering the actors and JIDs that provide them, use the #request method:

In this example, you get a hash of jids and their results, which should be
arrays of numbers from any agent that matches the given resources.

results_hash = @agent.request('/list', :all, :cluster => '/cluster/rd00', :resource => '/gem')

=== Vertebra Clients -- vertebra

The second, and more simple method, is to use the vertebra command line tool,
'vertebra'.  It allows one to do discovery and dispatch ops without having a
persistently running client agent, and without using vshell.

vertebra /gem/list res:/cluster/rd00 res:/slice/0

vertebra --help

vertebra /OP [vertebra-flags] [op arguments]
  --all             Dispatch the op with a scope of 'all'.  This is the default.
  --single          Dispatch the op with a scope of 'single'.
  --config FILENAME Specify a config file to use. If not specified, this
                    defaults to HOME/.vertebra/vertebra
  --jid JID         The JID to use to connect to vertebra. This overrides
                    anything specified in the configuration file.
  --herault-jid JID The JID of the herault instance to query for discovery.
  --password PWD    The password to use with the jid to connect to vertebra.
  --yaml            Transform the op results to YAML before displaying them.
                    This tends to make them more human readable, and is the
                    default.
  --inspect         Display the results of the op in the Ruby inspect format.
  --log             Turn logging on. This will write an agent.PID.log file to
                    the temp directory, logging the CLI actions. Off by default.
  --help            Show this text.

Anything on the command line that is not one of the above flags is passed to
the operation.  In order to differentiate between resources and other strings
on the command line, one should preface any resource with 'res:'.

i.e.

vertebra /gem/list cluster=res:/cluster/rd00 slice=res:/slice/0

All resources that are provided on the command line will be used for discovery.

Primarily as a developer aid, one may also provide specific jids:

vertebra /gem/list jid:rd00-s00000@localhost/agent

It is a good idea to setup a configuration file for the vertebra command line
tool.  The command line looks for HOME/.vertebra/vertebra for its default
configuration file.  The file is a YAML formatted file:

jid: vertebra-client@localhost/agent
password: testing
herault_jid: herault@localhost/herault