Global

The global section contains container-level configuration that applies to all actors. In general, this information should be relocated to the Container Properties File .

At present, this is the only required section in the configuration file. The remaining sections (actors and topology are optional). For example, when using the web portal, actors can be created dynamically and they can be linked to each other using the portal interface.

The information in this section can be organized in the following groups:

• Timing

  This portion of the configuration section is responsible for configuring the internal clock used by the Orca container. The internal clock is configured by the following elements:

  • startTime The beginning of time value to be used when calculating internal clock cycles.

    Possible values: -1 use the real time the container starts, a positive long value number of milliseconds since January 1, 1970, 00:00:00 GMT.

  • cycleMillis The length of an internal cycle in milliseconds

    Possible values: a positive long number.

  • firstTick The first cycle the clock should start with.

    Possible values: a non negative long number.

  • manualTicks If true , the container clock will advance only manually, e.g, by explicit calls. If set to false , the container clock will advance automatically, driven by the computer's internal clock.

• Container GUID

  Each Orca container has a globally unique identifier. This section specifies the container GUID using the following elements:

  • containerGuid Container GUID

    Possible values: A globally unique identifier

• Location Configuration

  Each container supports at least one inter-actor communication protocol. This section is used to describe all supported protocols. In case the container supports only local communication this section can be omitted.

  Location configuration is controlled by the following elements:

  • locations This is a complex element that contains one or more location elements. Each location element has the following attributes:
    • protocol Name of the protocol supported by the container.

      Possible values: local local communication (applicable only to actors in the same container), soap SOAP communication, xmlrpc , communication based on XML-RPC.

    • url URL associated with the specific protocol. This field is optional and protocol specific. The local protocol does not require this field. The soap protocol requires this to be the path to the root of the axis services URI, e.g., http://some.host.com/orca/services/. The xmlrpc protocol is currently not supported.
• Container Database

  This section is responsible for providing information about the container database. Each Orca container is linked to a backend store, which is used to store container and actor information. The system currently supports MySql-based backends. Support for LDAP and in-memory storage is currently broken but may be reintroduced if there is sufficient demand.

  The container database configuration is a complex element, database , which consists of the following sub-elements:

  • className Name of the class implementing the container backend interface.

    Recommended value: orca.manage.container.db.MySqlContainerManagementDatabase

  • properties A complex element containing property elements describing properties with a given name and value. The following property names are supported:
    • db.mysql.server Location of the MySQL server (DNS name or IP address).
    • db.mysql.db Name of the database on the server.
    • db.mysql.user User name to use when connecting to the database server.
    • db.mysql.password Password to use when connecting to the database server.
    • db.admin.first First name of the admin user. This and the following properties are optional when running from the command line, but are required if using the web portal with a fresh database.
    • db.admin.last Last name of the admin user.
    • db.admin.login Login name for the admin user.
    • db.admin.password Password for the admin user.

      Note: The current version does not support passwords. This is not a problem and is not required when using Duke's WEBAUTH system. When using form-based authentication, however, the password will always be treated as "" (empty).

    • db.admin.roles Roles assigned by the admin user. This property should always have the following value home,users,broker,admin , unless new roles are added or/and you really know what you are doing.

A sample global configuration section looks similar to this:

 <global>
   <startTime>-1</startTime>
   <cycleMillis>1000</cycleMillis>
   <firstTick>0</firstTick>
   <manualTicks>false</manualTicks>
   <containerGuid>583c10bfdbd326ba:41946007:114e182f09d:-8000</containerGuid>
   <locations>
     <location protocol="local" />
   </locations>   
   <database>
     <className>orca.manage.container.db.MySqlContainerManagementDatabase</className>
     <properties>
        <!-- MySQL database connection settings -->
        <property name="db.mysql.server" value="localhost" />
        <property name="db.mysql.db" value="orca" />
        <property name="db.mysql.user" value="orca" />
        <property name="db.mysql.password" value="" />
        <!-- Admin user login -->
        <property name="db.admin.first" value="Orca" />
        <property name="db.admin.last" value="Admin" />
        <property name="db.admin.login" value="admin" />
        <property name="db.admin.password" value="admin" />
        <property name="db.admin.roles" value="home,users,broker,admin" />
     </properties>
   </database>
 </global>

Actors

This section specifies the configuration of one or more actors to be instantiated in the Orca container. This section is optional. It is possible to use the web portal to create actors dynamically.

The actor section contains one or more actor elements. Each actor element specifies the configuration of a single actor. The goal of most actor subelements is to specify the Java object that must be instantiated for a particular purpose, e.g., policy class, Shirako Plugin, etc. This is achieved using a recursive XML object descriptors . The structure of object descriptors is as follows:

• They start with a className element. The class name specifies the Java class that must be instantiated.

  Example:

  <className>orca.policy.core.AuthorityCalendarPolicy</className>

• An optional properties section can define one or more property elements, which represent (name, value) pairs to be passed to the instantiated object. For this process to work, the instantiated object must implement a method with the following signature:

  void configure(java.util.Properties properties) throws Exception;

  Example:

  <properties>
   <property name="propertyName" value="property value" />
   <property name="anotherPropertyName" value="another property value" /> 
  </properties>

• An optional parameters section can describe one or more typed parameter -s to be passed to the object. Those parameters are passed by invoking methods on the object. The schema for the parameter element is:

  <xsd:complexType name="parameter">
    <xsd:all>
      <xsd:element name="value" type="xsd:string" minOccurs="0" />
      <xsd:element name="instance" type="instance" minOccurs="0" />
      </xsd:all>
      <xsd:attribute name="name" type="xsd:string" use="required" />
      <xsd:attribute name="type" type="xsd:string" default="String" />
      <xsd:attribute name="base" type="xsd:string" use="optional" />
  </xsd:complexType>

  Here is how parameter elements are interpreted by the system:

  • The name attribute specifies the name of the method that will be invoked to set this parameter. If the value of the attribute is X , the actual method that will be invoked is setX .
  • The value attribute specifies the string representation of the value of the parameter when the parameter is a simple type (string, integer, long, boolean).
  • The type attribute specifies the type of the parameter. The currently supported types are:
    • string The value of the value attribute is treated as a java.lang.String.
    • integer The value of the value attribute is treated as a java.lang.Integer.
    • long The value of the value attribute is treated as a java.lang.Long.
    • boolean The value of the value attribute is treated as a java.lang.Boolean.
    • instance The value attribute is ignored and the instance element should represent an object that must be dynamically instantiated. This object is recursively specified using the same object descriptor format.
  • The base attribute specifies the type of the argument of the method that will be invoked to set the parameter. This attribute is optional, if not specified the base is derived from the value of the parameter.

  Example:

     <className>orca.cod.plugins.Site</className>
     <properties>
       <property name="inventory.storage" value="fetch gnathosaurus" />
       <property name="inventory.machines" value="demo001 demo002 demo003" />
       <property name="resource.pools.count" value="1" />
       <property name="resource.pool.0" value="1" />
       <property name="resource.pool.name.0" value="demo" />
       <property name="resource.pool.type.0" value="1" />
       <property name="resource.pool.properties.0" value="memory=2048,cpu=100,bandwidth=1000" />
       <property name="resource.pool.machines.0" value="demo001 demo002 demo003 demo004" />
       <property name="resource.pool.ticket.units.0" value="4" />                                 
       <property name="resource.pool.ticket.start.0" value="0" />
       <property name="resource.pool.ticket.end.0" value="10000000" />                                    
       <property name="resource.pool.handler.packageId.0" value="583c10bfdbd326ba:-523aeda8:11644bdcf54:-8000" />
       <property name="resource.pool.handler.pluginId.0" value="1" />
       <property name="resource.pool.handler.properties.0" value="server.name=gnathosaurus,server.guid=583c10bfdbd326ba:-5bb4a8a:114482bd028:-8000,server.ip=172.16.0.2,server.base=sata/images/shirako/,server.control=152.3.144.204" />
     </properties>
     <parameters>
       <parameter base="orca.cod.plugins.NetworkConfigurationManager" name="NetworkManager" type="instance">
         <instance>
           <className>orca.cod.plugins.NetworkConfigurationManager</className>
           <parameters>
             <parameter base="orca.cod.plugins.NetworkConfiguration" name="NetworkConfiguration" type="instance">
               <instance>
                 <className>orca.cod.plugins.NetworkConfiguration</className>
                 <properties>
                   <property name="network.base" value="192.16.192.0" />
                   <property name="network.mask" value="255.255.224.0" />
                   <property name="network.subnet" value="255.255.255.0" />
                   <property name="network.min" value="10" />
                   <property name="network.gateway" value="" />
                 </properties>
               </instance>
             </parameter>
             <parameter base="orca.cod.plugins.DnsConfiguration" name="DnsConfiguration" type="instance">
               <instance>
                 <className>orca.cod.plugins.DnsConfiguration</className>
                 <properties>
                   <property name="dns.prefix" value="default" />
                   <property name="dns.zone" value="demo.orca.org" />
                   <property name="dns.mx" value="10 demo.orca.org" />
                 </properties>
               </instance>
            </parameter>
          </parameters>
        </instance>
      </parameter>
    </parameters>

The actor element consists of the the following subelements:

• name Specifies the name of the actor. Names should contain no spaces and should be globally unique.

  Example:

  <name>site</name>

• description Specifies an optional short description for the actor the actor.

  Example:

  <description>Some actor description.</description>

• instance An object descriptor for the actor. While the whole object can be described recursively in this subelement, certain elements must be specified in the following subelements (mapper, plugin).

  Example:

  <instance>
   <className>orca.shirako.core.Authority</className>
  </instance>

• mapper An object descriptor for the actor policy. Please consult this page for a list of the policies in the core polcies package.

  Example:

   <mapper>
     <className>orca.policy.core.AuthorityCalendarPolicy</className>
     <parameters>
       <parameter base="orca.policy.core.IResourceControl" name="ResourceControl" type="instance">
         <instance>
           <className>orca.cod.control.IdControlChange</className>
           <properties>
             <property name="resource.type" value="1" />
           </properties>
         </instance>
       </parameter>
     </parameters>
   </mapper>

• plugin An object descriptor for the actor Shirako plugin. Please consult this page for a description of actor-specific Shirako plugins.

  Note: Each actor must have a Shirako plugin!

  Example: See actor configuration example that follows.

Putting all together, the configuration fo a single actor looks like this:

<actor>
 <name>site</name>
 <description>site</description>
 <instance>
   <className>orca.shirako.core.Authority</className>
 </instance>
 <mapper>
   <className>orca.policy.core.AuthorityCalendarPolicy</className>
   <parameters>
     <parameter base="orca.policy.core.IResourceControl" name="ResourceControl" type="instance">
       <instance>
         <className>orca.cod.control.IdControlChange</className>
         <properties>
           <property name="resource.type" value="1" />
         </properties>
       </instance>
     </parameter>
   </parameters>
 </mapper>
 <plugin>
   <className>orca.cod.plugins.Site</className>
   <properties>
     <!-- Storage servers to be transferred to this site -->
     <property name="inventory.storage" value="fetch gnathosaurus" />
     <!-- Physical machines to be transferred to this site -->
     <property name="inventory.machines" value="demo001 demo002 demo003" />
     <!-- Resource pool configuration -->
     <property name="resource.pools.count" value="1" />
     <!-- First resource pool configuration -->
     <property name="resource.pool.0" value="1" />
     <property name="resource.pool.name.0" value="demo" />
     <property name="resource.pool.type.0" value="1" />
     <property name="resource.pool.properties.0" value="memory=2048,cpu=100,bandwidth=1000" />
     <property name="resource.pool.machines.0" value="demo001 demo002 demo003 demo004" />
     <!-- Source ticket configuration -->
     <property name="resource.pool.ticket.units.0" value="4" />                                 
     <property name="resource.pool.ticket.start.0" value="0" />
     <property name="resource.pool.ticket.end.0" value="10000000" />                                    
     <!-- Handler configuration -->
     <property name="resource.pool.handler.packageId.0" value="583c10bfdbd326ba:-523aeda8:11644bdcf54:-8000" />
     <property name="resource.pool.handler.pluginId.0" value="1" />
     <property name="resource.pool.handler.properties.0" value="server.name=gnathosaurus,server.guid=583c10bfdbd326ba:-5bb4a8a:114482bd028:-8000,server.ip=172.16.0.2,server.base=sata/images/shirako/,server.control=152.3.144.204" />
   </properties>
   <parameters>
     <parameter base="orca.cod.plugins.NetworkConfigurationManager" name="NetworkManager" type="instance">
       <instance>
         <className>orca.cod.plugins.NetworkConfigurationManager</className>
         <parameters>
           <parameter base="orca.cod.plugins.NetworkConfiguration" name="NetworkConfiguration" type="instance">
             <instance>
               <className>orca.cod.plugins.NetworkConfiguration</className>
               <properties>
                 <property name="network.base" value="192.16.192.0" />
                 <property name="network.mask" value="255.255.224.0" />
                 <property name="network.subnet" value="255.255.255.0" />
                 <property name="network.min" value="10" />
                 <property name="network.gateway" value="" />
               </properties>
             </instance>
           </parameter>
           <parameter base="orca.cod.plugins.DnsConfiguration" name="DnsConfiguration" type="instance">
             <instance>
               <className>orca.cod.plugins.DnsConfiguration</className>
               <properties>
                 <property name="dns.prefix" value="default" />
                 <property name="dns.zone" value="demo.orca.org" />
                 <property name="dns.mx" value="10 demo.orca.org" />
               </properties>
             </instance>
          </parameter>
        </parameters>
      </instance>
    </parameter>
    <parameter base="orca.shirako.api.IDatabase" name="Database" type="instance">
      <instance>
        <className>orca.cod.plugins.db.MySqlAuthorityCodDatabase</className>
        <properties>
          <property name="db.mysql.server" value="localhost" />
          <property name="db.mysql.db" value="orca" />
          <property name="db.mysql.user" value="orca" />
          <property name="db.mysql.password" value="" />
        </properties>
      </instance>
    </parameter>
    <parameter base="orca.shirako.plugins.config.Config" name="Config" type="instance">
      <instance>
        <className>orca.cod.plugins.config.CodAntConfig</className>
      </instance>
    </parameter>
  </parameters>
 </plugin>
</actor>

Note: The documentation of this section is incomplete. We are working on providing more information. Please check back later.

Topology

This section specifies the interconnections between actors residing in this container. Each actor can be connected to an actor within the same container, or to a remote actor. Local communication can use either the local or the soap protocol, but remote communication must be based on the soap protocol.

Note: The documentation of this section is incomplete. We are working on providing more information. Please check back later.