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:

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" ?>

<site>
 <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>
  </child>

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

  <!-- 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>
  </child>

  <!-- 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>
  </child>
 </vobject>
</site>

2.3.4. Standard Plugins

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

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.