Latest revision as of 16:33, 22 February 2022

 

Home

 

Download

 

News

 

Support

 

Admin

 

Dev

 

Screen Shots

 

Grid List

 

Bugs

Languages:

English    Deutsch    Français    日本語

[edit] Introduction

ROBUST stands for redesigned OpenSimulator Basic Universal Server Technology (ROBUST). It leverages the system of in and out connectors and services that was developed for the Hypergrid and OpenSimulator. 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.

This page is about use and configuration or ROBUST. There are separate pages for learning more about the services themselves.

[edit] 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 OpenSimulator 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;"

[edit] 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

• -logconfig

Instruct log4net to use this file as configuration file

• -prompt

Override the server prompt

[edit] Configuration File

[edit] 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

[edit] Section [Network]

• Port

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

[edit] 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.

[edit] 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

[edit] 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.

[edit] An Example Conversion From UGAIM To UGRM

This section will apply if you're migrating an existing OpenSimulator 0.6.6 installation to OpenSimulator 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.

[edit] An Example Conversion From UGRM To URM

This section will only apply if you're migrating from OpenSimulator 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.

[edit] An Example Conversion From URM To ROBUST

This section will only apply if you're migrating to the very latest Git master OpenSimulator 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 ROBUST 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.

[edit] Tips

If you're using MySQL in a standalone, you might see an error like this when you first start OpenSimulator 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.

[edit] Moving any service to its own ROBUST shell

This section contains advanced material. Proceed with caution

By design the Robust services are meant to be capable of running on their own connecting to each other. This is mostly true, but some services are now bound directly to other services they depend upon. Additionally, services are meant to run independently, allowing for multiple instances of services to run and process data, this also works only for some services due to the addition of caches in various places.

A good start to break up the load within Robust is to move heavy services out of a main Robust instance. Usually this means moving Inventory out first, followed by Groups and Presence. In most larger grids this usually distributes the load of these somewhat evenly.

To make breaking things up easier and less complex to configure it is wise to use the Include functionality to configure services individually and combine the configuration of them with the Service list to build the configurations of each Robust instance. This removes the need to configure each Robust.ini with all its services for each instance.

• Start by making a copy of the Robust.ini.example or Robust.HG.ini.example.
• Create two folders, one for LOCAL and one for REMOTE. These will hold the individual service configurations.
• Create a file for Robust.ini, Inventory.ini, Groups.ini and Presence.ini. These will hold the instance configurations copied from the .example configs.

With this structure in place, we can begin to pull apart the .example configuration and place respective individual service configurations within. These configurations will come in two different forms, as the folder names would suggest. One is for LOCAL services that live within the same Robust instance and depend on each other. The other is for REMOTE service configurations that connect to services running in other Robust instances.

The main .ini files simply contain the Network configuration, the service list and Includes for the respective configurations.

• From .example configuration copy section [Const], [Startup], [ServiceList] and [Network]
• Add [Architecture] section below
• Create Include-"Respective Robust service" = "location of file" for every service listed below

The finished configuration including the sections, which we will later configure properly, and all the Includes to the individual services, which are:

 Hypergrid
 AccessControl
 DatabaseService
 AssetService
 GridInfoService
 LoginService
 GatekeeperService
 LibraryService
 UserAgentService		 		
 AuthenticationService 			
 UserAccountService 				
 GridUserService 				
 AgentPreferencesService 		
 HGAssetService			 		
 InventoryService 				
 GridService 					
 OpenIdService 					
 PresenceService			 		
 AvatarService			 		
 FriendsService			 		
 EstateService			 		
 MapImageService			 		
 HGInventoryService		 		
 HGFriendsService			 	
 HGInstantMessageService		 	
 Messaging					 	
 Groups						 	
 UserProfilesService
 MuteListService

For each oth these we must now configure the LOCAL and REMOTE version. We do this despite some of them not being able to work in separate Robust instances, it simply serves to make it easier to know what's what.

Presence, UserAgentService, AgentPreferencesService and GridUserService have some dependency on each other that cannot be resolved via connectors, they have to remain in the same instance. Presence has a cache, which means using multiple instances of Presence is not possible without data conflicting.

Each service has a local module and a URI it can use. Internally both establish a connection to the service and provide the endpoint to Robust. Example InventoryService:

LOCAL

 [InventoryService]
     LocalServiceModule = "OpenSim.Services.InventoryService.dll:XInventoryService"

REMOTE

 [InventoryService]
    InventoryServerURI = "http://mygrid.com:8005"

Unfortunately not all of these are documented or follow the same naming scheme.

With both these files now set we can include them in the Architecture section we created before by pointing at the respective file. For all instances of Robust not running inventory we use the REMOTE file and for the instance that will handle inventory the LOCAL one. Example of main Robust instance:

 [Architecture]
   Include-InventoryService = "/REMOTE/InventoryService.ini"

Lastly we need to configure the ServiceList section. For the example of the main Robust instance simply comment the InventoryInConnector. In the Robust instance that will house the inventory service we leave the line intact as:

 InventoryInConnector = "${Const|PrivatePort}/OpenSim.Server.Handlers.dll:XInventoryInConnector"
 

Finally don't forget to check LoginService SRV_ directives to point to the correct instance and port.

[edit] Network Configuration

Under normal circumstances configuring the Network section with unique ports for both public and private ports makes sure each instance of Robust can properly bind to one. Of course that means on the GridCommon.ini the individual services using different ports needs to be reflected as well.

 [InventoryService]
   InventoryServerURI = "http://mygrid.com:8005"

However, there is a way to avoid this complexity and make access to the grid a lot easier to configure and handle configurations that use multiple instances of the same service Robust instance. For this a webserver with proxy capabilities is needed such as haproxy or nginx.

For the inventory example we can create a subdomain of inventory.mygrid.com pointing at the grid servce IP. In nginx we configure a server to listen to requests to that subdomain and proxy them to our inventory Robust instance.

 server {
   listen 80;
   
   server_name inventory.mygrid.com;
   
   location / {
     client_max_body_size 64M;
     proxy_set_header X-Real-IP  $remote_addr;
     proxy_set_header X-Forwarded-For $remote_addr;
     proxy_set_header Host $host;
     proxy_pass  http://inventory;
   }
 }
 
 upstream inventory  {
   ip_hash;
   server 127.0.0.1:8005;
   server 127.0.0.1:8006;
 }
 

This means we can configure GridCommon.ini to point InventoryServerURI to "http://inventory.mygrid.com" omitting the port, making configuration a lot more straight forward.

For most services only the public port needs to be forwarded, some HG services require both. You can still directly supply the ports in GridCommon.ini to increase security while retaining connections though.

[edit] Running a distributed setup

In order to run Robust with a specific configuration we need to start it with the -inifile parameter pointing to the respective instance configuration:

 (mono) Robust.exe -inifile=config/Inventory.ini

You may want to append the logfile parameter as well to split the log files for easier viewing:

 (mono) Robust.exe -inifile=config/Inventory.ini -logfile=Inventory.log
 

If you have done all configuration correctly you should see no red errors in the console and no mentions of connection failures.

[edit] Examples

Below are configurations graciously provided by Zetamex Network as an example of the distributed system. Note that these are not updated and may contain out of date configuration parameters or unsupported parameters. These are simply meant to illustrate the possibility of this setup and how far it can be pushed and still work. They should provide a good indication and starting point to understand this setup if the explanation above is too abstract and generalised.

https://github.com/Tampa/OpenSim-Split-Robust-Example

[edit] Additional Examples

WxService - An example ROBUST service