International school projects

OpenSimulator grid mode performance

Installing OpenSimulator with better performance in mind is needed for international school projects, that would require 50-60 concurrent students in a single region. This document describes how to install OpenSimulator in grid mode.

• OpenSimulator performance
• Installing OpenSimulator in grid mode
• Testing OpenSimulator in grid mode on localhost
• Installing Oligo Academy tools in grid mode

• OpenSimulator documentation
• Using grid mode for better scalability
• MySQL GUI tools
• Experimental add-on only for testing

Hosting OpenSimulator on the free MariaDB database

The free MySQL compatible database MariaDB can be used for running OpenSimulator on a low cost virtual private server like for example Contabo VPS with the easy administration user interface Plesk running both Linux and Windows. 

OpenSimulator performance

In this document we will describe how to use OpenSimulator grid mode for better performance, but still be able to use most of the functionality in the Oligo Dashboard – except user account creation, that needs to be done in the OpenSimultor robust console with the command “create user”.

The goal of running OpenSimulator in grid mode is to distribute the work load between more processes, to gain better performance with many active users, especially letting data services handle the login process gives users in the simulators a better performance experience. You can install one simulator process (OpenSim.exe) for all your regions, if users only use one region at a time, but if many regions are in use at the same time, then running multiple OpenSim.exe for different regions makes sense.

• Data services (Robust.exe)
• Simulators (OpenSim.exe)
  • Simulator 1 with Oligo Dashboard (OpenSim.exe running one large 1024 x 1024 size region)
  • Simulator 2 with Oligo Dashboard (OpenSim.exe running two medium 512 x 512 size regions)
  • Simulator 3 with Oligo Dashboard (OpenSim.exe running four normal 256 x 256 size regions)
• Database server (MySQL or MariaDB)

Use a naming convention for  login names
For the special user Master Avatar the last name Avatar must  be specified, but other users can be created with the last name Resident, that does not need to be specified on login. This would allow your IT department to create some anonymous login names like Uni-login used in Denmark by all public schools, to protect students identity. If for example the students Uni-login is niha13d then in Robust console type “create user” and press enter to then specify niha13d as first name and Resident as last name and some password. The student can now login using niha13d and their password, without specifying a last name.

If you manage logins for many schools you could also use login last name for identifying the school and then student must type their anonymous first name and school abbreviation as last name when logging in. For teachers to easily communicate to their students you could create a group in OpenSimulator using the Oligo Dashboard, that is named like the class and owned by the teacher, with all their students as members.

Installing OpenSimulator in grid mode

First you must install the MySQL database and create the database opensimgrid and create the user opensimgrid, that has full access to the opensimgrid database only. Installing MySQL on different platforms is beyond the scope of this manual, but I normally use a MySQL GUI tool or this Ubuntu Linux guide from a hosting provider.

Start by downloading the current release of OpenSimulator and unzip the file to your installation folder of choice.

When installing OpenSimulator in grid mode we need to do three steps after we create the MySQL database as described in the previous section:

1. Modify the OpenSimulator config files in the bin folder for both OpenSim and Robust.
2. Start the Robust.exe data services process and create the first user called Master Avatar with password 2222.
3. Start the OpenSim.exe simulator process that will create any regions defined in Regions.ini, when it’s asks for estate and other information just accept the defaults by pressing enter

\bin
- OpenSim.ini
- Robust.ini

\bin\config-include
- GridCommon.ini
- Grid.ini

\bin\Regions
- Regions.ini

If you want to have multiple OpenSim.exe processes for different regions, just make a copy of the bin folder and modify the Regions.ini accordingly in each bin installation folder.

\bin\OpenSim.ini

[Groups]
ServicesConnectorModule = "Groups Remote Service Connector"
MessagingModule = "Groups Messaging Module V2"
NoticesEnabled = true
MessageOnlineUsersOnly = true


[Architecture]
; Include-Architecture = "config-include/Standalone.ini"
Include-Architecture = "config-include/Grid.ini"

\bin\Robust.ini

[ServiceList]
GroupsServiceConnector = "${Const|PrivatePort}/OpenSim.Addons.Groups.dll:GroupsServiceRobustConnector"

[DatabaseService]
ConnectionString = "Data Source=localhost;Database=opensimgrid;User ID=opensimgrid;Password=2222;Old Guids=true;"

[GridInfoService]
gridname = "Oligo Academy"
gridnick = "oligo"

\bin\config-include\GridCommon.ini

[DatabaseService]
; Include-Storage = "config-include/storage/SQLiteStandalone.ini";
StorageProvider = "OpenSim.Data.MySQL.dll"
ConnectionString = "Data Source=localhost;Database=opensimgrid;User ID=opensimgrid;Password=2222;Old Guids=true;"

\bin\config-include\Grid.ini should not be changed it just loads GridCommon.ini were you do your changes

\bin\Regions\Regions.ini

; Define region Region0, Region1,..,Region6 with different sizes
;  1024         512    256
; +------------+------+---+
; |Oligo       | 1    | 3 |
; |            |      +---+
; |            |      | 4 |
; |            +------+---+
; |            | 2    | 5 |
; |            |      +---+
; |            |      | 6 |
; +------------+------+---+

; Each region must have a unique name, RegionUUID, Location and InternalPort from 9000-9010 
; Currently port 9000-9006 are in use and only port 9007-9010 are free for custom regions.

; Configure one large 1024x1024 region
[Oligo]
RegionUUID = 11111111-2222-3333-4444-555555555550
Location = 1000,1000
SizeX = 1024
SizeY = 1024
SizeZ = 4096
InternalAddress = 0.0.0.0
InternalPort = 9000
ResolveAddress = False
ExternalHostName = SYSTEMIP
MaptileStaticUUID = 00000000-0000-0000-0000-000000000000

; Configure two medium 512x512 regions
[Region1]
RegionUUID = 9755f60d-5390-4bf1-b69b-5aeff998afa1
Location = 1005,1000
SizeX = 512
SizeY = 512
SizeZ = 4096
InternalAddress = 0.0.0.0
InternalPort = 9001
ResolveAddress = False
ExternalHostName = SYSTEMIP
MaptileStaticUUID = 00000000-0000-0000-0000-000000000000

[Region2]
RegionUUID = 9755f60d-5390-4bf1-b69b-5aeff998afa2
Location = 1005,1002
SizeX = 512
SizeY = 512
SizeZ = 4096
InternalAddress = 0.0.0.0
InternalPort = 9002
ResolveAddress = False
ExternalHostName = SYSTEMIP
MaptileStaticUUID = 00000000-0000-0000-0000-000000000000

; Configure four small 256x256 regions
[Region3]
RegionUUID = 9755f60d-5390-4bf1-b69b-5aeff998afa3
Location = 1008,1000
SizeX = 256
SizeY = 256
SizeZ = 4096
InternalAddress = 0.0.0.0
InternalPort = 9003
ResolveAddress = False
ExternalHostName = SYSTEMIP
MaptileStaticUUID = 00000000-0000-0000-0000-000000000000

[Region4]
RegionUUID = 9755f60d-5390-4bf1-b69b-5aeff998afa4
Location = 1008,1001
SizeX = 256
SizeY = 256
SizeZ = 4096
InternalAddress = 0.0.0.0
InternalPort = 9004
ResolveAddress = False
ExternalHostName = SYSTEMIP
MaptileStaticUUID = 00000000-0000-0000-0000-000000000000

[Region5]
RegionUUID = 9755f60d-5390-4bf1-b69b-5aeff998afa5
Location = 1008,1002
SizeX = 256
SizeY = 256
SizeZ = 4096
InternalAddress = 0.0.0.0
InternalPort = 9005
ResolveAddress = False
ExternalHostName = SYSTEMIP
MaptileStaticUUID = 00000000-0000-0000-0000-000000000000

[Region6]
RegionUUID = 9755f60d-5390-4bf1-b69b-5aeff998afa6
Location = 1008,1003
SizeX = 256
SizeY = 256
SizeZ = 4096
InternalAddress = 0.0.0.0
InternalPort = 9006
ResolveAddress = False
ExternalHostName = SYSTEMIP
MaptileStaticUUID = 00000000-0000-0000-0000-000000000000

Testing OpenSimulator in grid mode on localhost

When logging into an OpenSimultor in grid mode the FireStorm viewer will connect to a domain name on port 8002, which for you local machine means localhost:8002. This grid entry does not exist in the FireStorm viewer grid list and I can not add it due to an error in the FireStorm viewer under Preferences, OpenSim and Grid manager. Students that connect to the grid server from the yourdomain:8002 should not have this problem or if they do they can use the Singularity viewer or add the entry manually.

To work around testing on localhost:8002 it I added a line to my hosts file with a fictive domain name called opensim-grid (/etc/hosts on Mac or C:\Windows\System32\drivers\etc\hosts on Windows)

127.0.0.1 localhost-grid

Then i browsed to grids.user.xml file in the folder %APPDATA%\Firestorm_x64\user_settings in Windows and inserted the grid entry below just before <key>localhost:9000</key>.

<key>localhost-grid:8002</key>
<map>
<key>LastModified</key>
<date>2011-08-28T12:00:00Z</date>
<key>grid_login_id</key>
<string>localhost-grid:8002</string>
<key>gridname</key>
<string>localhost-grid</string>
<key>gridnick</key>
<string>localhost-grid</string>
<key>login_identifier_types</key>
<array>
<string>agent</string>
<string>account</string>
</array>
<key>loginpage</key>
<undef />
<key>loginuri</key>
<array>
<string>http://localhost-grid:8002</string>
</array>
<key>name</key>
<string>localhost-grid:8002</string>
<key>platform</key>
<undef />
<key>slurl_base</key>
<string>hop://localhost-grid:8002/</string>
</map>

This gives me to option to login to OpenSimulator running in grid mode on localhost-grid:8002, instead of OpenSimulator running in standalone mode on localhost:9000.

Installing Oligo Academy tools in OpenSimulator running in grid mode

Download the Oligo Academy tools packaged with the Docker image (oligo_academy_opensim), there you will find the OpenSimulator add-ons in the /bin folder and the Oligo Dashboard in the /dashboard folder.

Even though the Oligo Academy tools were developed for a standalone OpenSimulator, to make it easy for a teacher to run in-class virtual world education using a Docker image, the tools can also be installed on OpenSimulator in grid mode for an international school project. In OpenSimulator grid mode creating users is done in the Robust console, but other than that all Oligo Dashboard functionality should work in grid mode.

The Adaptive Learning System OpenSimulator add-on is the backend API for the teacher dashboard. The add-on is a single DLL file and some configurations folders and files, that you just copy to the OpenSim bin folder and then restart the OpenSim.exe process.

Adaptive Learning System

/bin
- AdaptiveLearningSystem.dll  (the add-on module)
- DotNetZip.xml (external zip library configuration)
- DotNetZip.dll  (external zip library)
- OpenSim.Data.SQLite.dll (added limited group v2 support in SQLite, full support in MySQL/MariaDB)
- System.Web.Helpers.dll (external web helper library for parsing JSON)

/bin/Regions/
- Regions.ini (defines one 1024x1024, two 512x512 and four 256x256 regions)

/bin/addon-modules/AdaptiveLearningSystem/config
- AdaptiveLearningSystem.ini (add-on config file)

/bin/addon-modules/AdaptiveLearningSystem/data/logs

/bin/addon-modules/AdaptiveLearningSystem/data/maps
- EmptyRegion1024x1024.oar (empty large region for deleting content)
- EmptyRegion512x512.oar (empty medium region for deleting content)
- EmptyRegion256x256.oar (empty normal region for deleting content)

/bin/addon-modules/AdaptiveLearningSystem/data/objects
- OligoAvatars.iar (alian avatar body parts to make students look alike)
- defaultstripe.png (fixing OpenSimulator missing file issue)
- hud.iar (example Head Up Display (HUD))

The teacher dashboard is a self hosting React web app, that can be installed on any server with NodeJS.

Dashboard

/dashboard
- build
- package.json

Change directory to the /dashboard folder and run the following to install both global and project dependencies, before starting the web app on port 9080 with the serve script.

npm install -g cross-env 
npm install -g serve 
npm install 

npm run serve

Open a browser at localhost:9080 and you should see the Dashboard below, after log-in as a superuser. In the Oligo Academy setup we normally create a superuser called Master Avatar with password 2222, but if you have created another superuser, you should use that credentials.

OpenSimulator documentation

• The OpenSimulator configuration page describes the different database options.
• The OpenSimulator performance page describes the different bottlenecks and setup options.
• The OpenSimulator groups page describes how to enable groups
• The OpenSimulator robust data services description

The configuration page states that MySQL is the recommended database, but MariaDB is fully supported. MariaDB is a fork of MySQL, made by the original developers of MySQL and guaranteed to stay open source, unlike MySQL that was bought by a commercial company in 2010. MariaDB must use the character set utf8mb3 (3 bytes) even though some installations default to uft8mb4 (4 bytes).

Using Grid mode for better scalability

OpenSimulator has limited scalability in multiple areas, due to it’s single threaded implementation. Expensive data service operations like login, caching assets, loading users inventory or loading/saving archive files will have a great impact on the performance.

This solve these performance problems you should install OpenSimulator in Grid mode using Robust.exe process to run data services and multiple OpenSim.exe processes for one large or few small regions. Each OpenSim.exe process is still single threaded, but we are just reducing the workload on each thread.

You can even split the load of the Robust.exe and run multiple data services in each their thread, too take advantage of a multi thread processor. You can of cause install all of the above on a single server with lots of memory and multiple processors, but the normal way to ensure scalability is to split the application into multiple tiers on several virtual servers, where each tier can be scaled separately when needed. You might start out with just 3 servers for data services, all simulators and a database server. If the assets service becomes a bottle neck you can run it on another Robust.exe server. If the server with all simulators is the bottleneck you can run each of the 3 simulators on their own server. The MySQL and MariaDB can run as a cluster for better performance.

MySQL GUI tools

When working on Windows I prefer using the SQLyog GUI tool for MySQL, on other platforms I normally use the command line tools, but Contabo VPS servers come with Plesk and phpMyAdmin web interface and on Mac you could use SequelPro.

In SQLyog under the menu Database, Create database you can create the new OpenSimulator database:

Then under the menu Tools, User manager you press “Add New User” to create a new opensimgrid user with some password. Then select the user opensimgrid in the dropdown and the database opensimgrid in the list below and check the “Select/Deselect all” to grant the user full rights on the opensimgrid database.