ROBUST

Revision as of 06:31, 22 April 2010

Redesigned OpenSim Basic Universal Server Technology (ROBUST)

Concepts

ROBUST leverages the system of in and out connectors and services that was developed for the Hypergrid and OpenSim. It replaces OGS1 with a modular architecture that can be easily extended using core and 3rd party modules.

ROBUST is a flexible server shell that can load the same modules already used by regions. This allows for nearly 100% code reusability and great flexibility.

The ROBUST server loads "in" connectors as specified in the configuration file. These connectors then load the required processing and storage modules and/or "out" connectors. Through this architecture, each ROBUST server can run any or all grid services, and/or act as a proxy for grid services.

Configuration

The server reads a configuration file at startup, which defaults to the name of the assembly with .ini appended. The default name for the ROBUST server is Robust.exe, therefore the default configuration file is Robust.ini. An Robust.ini.example file is provided with the OpenSim kit. The default port for all services running in ROBUST is 8003 as you can see below.

; * The startup section lists all the connectors to start up in this server
; * instance. This may be only one, or it may be the entire server suite.
; * Multiple connectors should be seaprated by commas.
; *
; * These are the IN connectors the server uses, the in connectors
; * read this config file and load the needed OUT and database connectors
; *
[Startup]
ServiceConnectors = "OpenSim.Server.Handlers.dll:AssetServiceConnector,OpenSim.Server.Handlers.dll:InventoryServiceInConnector"   

; * This is common for all services, it's the network setup for the entire
; * server instance
; *
[Network]
port = 8003

; * As an example, the below configuration precisely mimicks the legacy
; * asset server. It is read by the asset IN connector (defined above)
; * and it then loads the OUT connector (a local database module). That,
; * in turn, reads the asset loader and database connection information
; *
[AssetService]
LocalServiceModule = "OpenSim.Services.AssetService.dll:AssetService"
DefaultAssetLoader = "OpenSim.Framework.AssetLoader.Filesystem.dll"
AssetLoaderArgs = "assets/AssetSets.xml"
StorageProvider = "OpenSim.Data.MySQL.dll"
ConnectionString = "Data Source=localhost;Database=grid;User ID=grid;Password=grid;"

; * This configuration loads the inventory server modules. It duplicates
; * the function of the legacy inventory server
; *
[InventoryService]
LocalServiceModule = "OpenSim.Services.InventoryService.dll:InventoryService"
UserServerURI = "http://127.0.0.1:8002"
SessionAuthentication = "false"
StorageProvider = "OpenSim.Data.MySQL.dll"
ConnectionString = "Data Source=localhost;Database=grid;User ID=grid;Password=grid;"

Command Line Arguments

• -inifile

Specify the location of the .ini file to read instead of the default

• -console

Specify console type, one of basic, local or rest

• -logfile

Specify the logfile this server will log to

• -prompt

Override the server prompt

Configuration File

Section [Startup]

• ServiceConnectors

Comma separated list of service IN connectors. The format of each entry is <dllname>:<classname>. If a dll contains only one suitable class, the class name can be omitted.

• Prompt

Override the server prompt

• Console

Specify console type, one of basic, local or rest

• Logfile

Specify the logfile this server will log to

Section [Network]

• Port

Set the network port to listen on. All services will run on this port.

Connector Configurations

These configurations are provided by the connector modules and are not an integral part of the ROBUST server. Documentation to all possible options can be found in the documentation of the connector. This manual only lists the options present in the sample configuration file.

Section [AssetService]

• LocalServiceModule [Connector option]

A module specification (<dll>:<class>) that provides the services for this connector

• DefaultAssetLoader [Service option]

A dll containing the asset loader to use for loading the default asset set

• AssetLoaderArgs [Service option]

Path to load assets from (for the file system asset loader)

• StorageProvider [Service option]

Dll containing the database provider code

• ConnectionString [Service option]

Connection string to be passed to the database provider

Section [InventoryService]

• LocalServiceModule [Connector option]

A module specification (<dll>:<class>) that provides the services for this connector

• UserServerURI [Connector option]

URI to reach the user server at

• SessionAuthentication [Connector option]

Authenticate inventory sessions (default false!)

• StorageProvider [Service option]

Dll containing the database provider code

• ConnectionString [Service option]

Connection string to be passed to the database provider

Additional connectors may need additional sections to be added.

An Example Conversion From UGAIM To UGRM

This section will apply if you're migrating an existing OpenSim 0.6.6 installation to OpenSim 0.6.7. In this version, the name of the Robust server is OpenSim.Server.exe.

Converting from UGAIM to UGRM:

Kudos to diva and Melanie_t for helping and tolerating me (smxy).

My initial setup:

Full HG-enabled, Internet-accessible, Grid Mode system, using MySQL and split over two servers.

UGAIM and MySQL 5.0 run in two separate 32-bit CentOS 5.3 Xen VMs on a 64-bit CentOS 5.3 system.
Each region runs in its own instance of OpenSim.exe on a 32-bit Windows XP SP3 Home system.
OSWI runs on the Windows system too.

Bring down the regions. Bring down UGAIM.

Then, the port for the inventory server needs to be changed from 8004 to 8003 in

OpenSim.ini:           "inventory_server_url"          - For all regions and the UGRM server.

GridCommon.ini:        "InventoryServerURI"            - For all regions and the UGRM server.

UserServer_Config.xml: "default_inventory_server"      - For the UGRM server.

In the MySQL database, in the "users" table, the userInventoryURI field needs to be updated for all users.

In OSWI's config file, update "$userInventoryURI".

AssetServer_Config.xml and InventoryServer_Config.xml can be deleted from the UGRM server.

On the UGRM server, copy OpenSim.Server.ini.example to OpenSim.Server.ini and edit it, changing the "ConnectionString" entries appropriately, in the [AssetService] and [InventoryService] sections.

Bring up UGRM. Bring up regions.

Semi-unrelated Note: According to Melanie_t, any of the UGRM servers can be restarted independently, without needing to restart the other three. However, if you restart the UserServer, you must issue the command "register" (without the quotes) at the MessagingServer console, afterwards.

An Example Conversion From UGRM To URM

This section will only apply if you're migrating from OpenSim 0.6.7 to 0.6.8 In this version, the name of the Robust server is OpenSim.Server.exe.

Converting from UGRM to URM:

This is a continuation of my "UGAIM to UGRM" example above. I may merge the two examples, eventually.

Bring down the regions. Bring down UGRM.

Make sure that you don't override any of these files - they should be used as they come out of the repository:

 config-include/Grid.ini
 config-include/GridHypergrid.ini
 config-include/Standalone.ini
 config-include/StandalioneHypergrid.ini

Also make sure that you include new additions in config-include/*Common.ini.example into your config-include/*Common.ini

Then, the port for the grid server needs to be changed from 8001 to 8003 in

UserServer_Config.xml:      "default_grid_server"     - For the URM server.

MessagingServer_Config.xml: "default_grid_server"     - For the URM server.

On the URM server, save a copy of your existing OpenSim.Server.ini. Copy OpenSim.Server.ini.example to OpenSim.Server.ini. Edit it to reflect any changes you made in the previous version. Then edit the "ConnectionString" entry, appropriately, in the [GridService] section.

GridServer_Config.xml can be deleted from the URM server.

Bring up URM. Bring up regions.

An Example Conversion From URM To R

This section will only applies if you're migrating to the very latest Git master OpenSim code (since commit a9580eb on Tue Mar 2nd 2010)

Starting in the presence-refactor branch, the default configuration is one single server running ALL resource services, plus whatever number of simulators you have.

Bring down the regions. Bring down URM.

Make sure that you don't override any of these files - they should be used as they come out of the repository:

 config-include/Grid.ini
 config-include/GridHypergrid.ini
 config-include/Standalone.ini
 config-include/StandalioneHypergrid.ini

Also make sure that you include new additions in config-include/GridCommon.ini.example into your config-include/GridCommon.ini

On the R server, copy Robust.ini.example to Robust.ini. Edit it to reflect your setup. In particular edit the "ConnectionString" entry, appropriately. Also notice new configuration variables in the [GridService] section, where you can now define default and fallback regions for your grid.

If you want your grid to support the Hypergrid functionality -- both letting your users go out and letting outside users come in -- use Robust.ini.HG.example as the basis of your setup instead of Robust.ini.example. Copy it to Robust.ini, and make the changes there.

All *_Config.xml files are now obsolete and can be removed.

Start your services:

$ [mono] Robust.exe

Note that the default configuration starts 2 processes, one listening in port 8002 and the other listening in 8003. We have placed the services that need to be exposed to the internet in port 8002; all services that don't need to be exposed are in port 8003. To secure your grid you can now put port 8003 behind your firewall. Unless you know what you are doing, leave the port numbers exactly as they come out of the package; change only the host names everywhere they need to be changed.

Tips

If you're using MySQL in a standalone, you might see an error like this when you first start OpenSim after updating.

18:27:39 - [SERVICE BASE]: Failed to load plugin OpenSim.Data.IFriendsData from OpenSim.Data.MySQL.dll with args URI=file:friends.db,version=3, FriendsSystem.Reflection.TargetInvocationException: Exception has been thrown by the target of an invocation. ---> System.ArgumentException: Keyword not supported. Parameter name: uri

...

18:27:39 - Error loading plugin from OpenSim.Services.FriendsService.dll, exception System.Exception: Could not find a storage interface IFriendsData in the given StorageProvider OpenSim.Data.MySQL.dll

This is because the new StorageProvider parameters in config-include/Standalone.ini are all for SQLite. If you comment these out then things should work again.

Explanation of some services

• GatekeeperService
  • Hypergrid v1.5-related
  • for control of incoming foreign users
• UserAgentService
  • Hypergrid v1.5-related
  • for control of outgoing local users
• HGInventoryService
  • Hypergrid v1.5-related
  • optional
  • accompanies UserAgentService
  • allows access to home inventory in a "special" way
    • doesn't send root folder to outside grids
    • doesn't allow delete operations
• AvatarService
  • formerly known as avatar appearance

Moving any service to its own ROBUST shell

This section contains advanced material. Normally you can ignore this.

If you have a large grid, you may want to run different sets of services in their own ROBUST shell in separate machines, instead of all in one. For example, you may want to single out the Login Service with all the other outside-the-firewall services in its own machine; the Grid Service in its own machine; the Asset Service in its own machine; etc. With ROBUST any service, or any combination of services, can be easily grouped into their own ROBUST shells. If so, do this:

• Copy Robust.ini.example to your own copy in each machine you want to run of these servers.
• Edit each. Pay attention to all the server connectors that are given in the [Startup] section. Pick & choose whichever you want in that particular machine.
• In each configuration section you now need to pay attention to the auxiliary service connectors, and, maybe, change them appropriately. For example, the Login Service needs to access the Inventory Service in order to get the user's inventory upon login. In the default configuration, that dependency is given under the [LoginService] section by the variable

InventoryService = "OpenSim.Services.InventoryService.dll:InventoryService"

If you separate the login service from the inventory service, the corresponding 'InventoryService' variable under [LoginService] should be changed to

   InventoryService = "OpenSim.Services.Connectors.dll:InventoryServicesConnector"

Then in the [InventoryService] section of this Login server config, you'd have

 [InventoryService]
   InventoryServerURI = "http://myinventoryserver.com:myport"

instead of what you have by default.

• Save the configuration and start the server as normal
• Note that you can start the server like this:

$ Robust.exe -inifile=OpenSim.MyServer.ini -logfile=/some/path/to/some/file

• Start all other ROBUST servers you may want to have
• In your simulators, make sure to update GridCommon.ini to point to the correct URLs
• Start your sims