[Bugs & Requests][Wiki]

2.3. Omnivos: The All Purpose VOS Server

2.3.1. Overview

OmniVOS is a general purpose VOS server: it is a background daemon that provides a VOS site, with various configurations or extensions. These extensions are provided to OmniVOS by plugin modules. All configuration of OmniVOS and its plugins is unified, but may be supplied in a file, on the command line, or by environment variables.

OmniVOS plugins can load Vobjects (e.g a 3D world) from a COD file, from files and directories on the local file system, or from a mySQL database; it can do revision control on objects; it can serve a web site over HTTP; and more — you can write your own plugins as well.

2.3.2. Command line basic options

Omnivos can be configured by giving options on the command line, by setting options in a configuration file, or by setting environment variables (with that order of precedence). Options which may always be given to Omnivos are given in table 1:

Table 2-1. Base Omnivos options and settings

Command lineLong optionDescription
-h Display help text. To get help for plugins, you must use a config file that loads those plugins.
-c file Load config file file.
-c vobjectconfigsection vobjectLook for vobject with the given name to load as the configuration section.
-L directorypluginpath directoryAdd specified directory to the search path when looking for plugins to load.
-o filelogfile fileSend log output to file. If file is - (one dash), then --nofork is automatically assumed, and log output is sent to standard output.
-v levelloglevel levelSet threshold log level.
-nnoforkIf given, Omnivos will not run in the background.
-i filepidfile fileWrite process ID into file after forking into the background.
-L directorypluginpath directoryAdd given directory to the plugin search path.
-qquietIf given, only log errors.
-d policydefaultsitepolicy policySet access control policy on site object.
 proto vip|vosSpecify protocol to use, either vip or vos.

2.3.3. Sample configuration file

The configuration for Omnivos is stored in a specific Vobject structure. As a result, Omnivos can load its configuration from any VOS file format. VOS supports the human-readable XML Object Description (XOD) file format, and a documented sample configuration file is given below:

<?xml version="1.0" ?>

 <vobject name="vosapp:configuration" defaultpolicy="core:read-only,property:read-only">

  <!-- Set the output logfile -->
  <property name="logfile">3dworld-blocks.log</property>

  <!-- Set a permissive default access control policy: -->
  <property name="defaultsitepolicy">core:accept-all,property:accept-all,site:accept-all,log-level-control:accept-all</property>

  <property name="pluginpath">plugins/.libs</property>
  <property name="pluginpath">plugins</property>

  <!-- Enable search -->
  <child name="search" type="vosapp:plugin.sharedobject">
    <property name="vosapp:plugin">libomniplg_search</property>

  <!-- Enable remote log control -->
  <child name="logctrl" type="vosapp:plugin.sharedobject">
    <property name="vosapp:plugin">libomniplg_logctrl</property>

  <!-- Load the world file.  This can load any supported format. -->
  <load file="worlds/blocks.cod.gz"
    defaultpolicy="core:read-only,property:read-only" />

  <!-- The avatar factory creates an avatar object on the server -->
  <!-- when a new visitor joins the world.  This allows people behind -->
  <!-- firewalls/NAT gateways to interact with other users since messages to their -->
  <!-- avatar go to the server, not to their own local host (those would -->
  <!-- be blocked by the firewall). -->
  <child name="avatar_factory" type="vosapp:plugin.sharedobject">
    <property name="vosapp:plugin">libomniplg_avatar_factory</property>
    <property name="vobject">world</property>
    <property name="model" file="default_avatar.md2" />
    <property name="skin" file="default_avatar.png" />
    <property name="hardrot">0 1 0 90</property>
    <property name="policy">factory.compound:accept-all</property>
    <property name="startingpos">-4 1 -4</property>
    <property name="startingrot">0 1 0 25</property>

  <!-- This turns the root 'world' object into a talkative object which  -->
  <!-- relays talk messages to other avatars in the world. -->
  <child name="talkative" type="vosapp:plugin.sharedobject">
    <property name="vosapp:plugin">libomniplg_talkative</property>
    <property name="vobject">world</property>
    <property name="send-policy">talkative:send-only</property>
    <property name="listen-policy">core:accept-all</property>

2.3.4. Standard Plugins

Here is a list of plugins that are currently included with Omnivos. libomniplg_avatar_factory

The avatar factory plugin initializes a Vobject to serve as a factory for creating and initializing avatars

Table 2-2. "avatar_factory" plugin options and settings

modelfile path to default avatar model
skinfile path to default avatar skin
vobjectvobject that will serve as the factory
hardrotapply fixed orentation change to the avatar model
startingposinitial avatar position
startingrotinitial avatar orientation
policyaccess control policy on the factory libomniplg_fspersist

Keep a VOS site in persistant store in the file system

Table 2-3. "fspersist" plugin options and settings

rootRoot directory for persistance data libomniplg_hypervos

Support HTTP access of HyperVOS services (generate XHTML/XML from vobject structures)

Table 2-4. "hypervos" plugin options and settings

http-portport to listen on for HTTP services
description-formatUse given description format when describing non-hypertext Vobjects. May be "HTML" or "RDF".
always-describeAlways return a description of requested object rather than assembling XML documents for XML type objects. libomniplg_ircbridge

Support HTTP access of HyperVOS services (generate XHTML/XML from vobject structures)

Table 2-5. "ircbridge" plugin options and settings

serverIRC server host to connect to
portIRC server port to connect to
channelIRC server channel to connect to
vobjectvobject to extend (will be made talkative if it isn't already) libomniplg_logctrl

Provides a remote interface for adjusting the logging output level on a site libomniplg_revcontrol

Revision control persistance backend plugin

Table 2-6. "revcontrol" plugin options and settings

rootRoot directory for revision control data libomniplg_talkative

Add talkative support to a Vobject

Table 2-7. "talkative" plugin options and settings

vobjectvobject to be talkative
send-policypolicy to set
listen-policypolicy to set

2.3.5. Running Omnivos servers at system boot

To run Omnivos servers on a Unix-like system at boot, an "init" script is provided. This script looks for a directory containing configuration files (/etc/omnivos/init on most systems). For each configuration file in the directory, an Omnivos server is started in the background with that config file, writing its log to /var/log/omnivos-config.log (on most systems), and it's PID to a similarly named file in /var/run (on most systems).

2.3.6. Writing an Omnivos plugin

Writing a plugin for Omnivos using C++ is simple. Your plugin must provide some C functions which Omnivos will call:

#include <vos/vos/vos.hh>

extern "C" {
    DECLARE_VOS_PLUGIN("my_plugin", 1, 0);

    PLUGIN_API void vosplugin_help(VOSPlugin::PluginHelp* help) {
        // This sets up the help text that will be displayed to the
	// user, and registers valid config file options.

        help->header = "Describe your plugin here";
        help->options.push_back(VOSPlugin::HelpOption("option", "Describe your option here"));

    PLUGIN_API void vosplugin_init(Vobject* config) {
       // Your configuration options are stored as child properties
       // of the config Vobject.
       // This is where the plugin hooks itself into the omnivos runtime.

vosplugin_help is called to initialize the help text for options available on this plugin.

vosplugin_init is called to actually tell the plugin module to initialize itself and install its hooks into the application.

See the VOS API documentation for full documentation of the VOSApp class, which implements the Omnivos framework. For examples of Omnivos plugins, see apps/omnivos/plugins in the VOS source code.

Note: When building plugin libraries using GNU libtool, don't forget to use the -module flag.