Latest revision as of 15:11, 26 February 2022

This article was last updated in 2014, since then a lot of things have changed and information is likely no longer accurate, proceed with caution!

[edit] OpenSim HowTo

Configuring a Grid

rev.20120620

compiled by "Zylek" (zy.zylek@gmail.com)

Disclaimer: the majority (or possibly all) of this document should be accurate. However, if you find any errors within it, please email Z about it and a new PDF revision will be created.

This tutorial describes how to install and configure OpenSimulator in grid mode on a Linux platform. Parts 1-5 provide steps for setting up the grid (dependencies, databases, & initialization files), while parts 6-10 provide steps for general grid usage (connecting, interacting, & managing the grid).

Acknowledgements: Thank you to everybody in #opensim freenode IRC for your feedback!

[edit] Part 1: Downloads & Dependencies

[edit] Required software

OpenSim (v0.7.3.1 or newer)
mono-complete (v2.4.3 or newer, important: mono must be the complete package plus -devel)
MySQL (v5.1 or newer, slightly older versions might be compatible)

[edit] OpenSim

Download OpenSim here: Download
Extract contents to an appropriate directory:

$ tar xvzf opensim-0.7.3.1.tar.gz

[edit] mono-complete

If your Linux distribution carries mono-complete in its repositories, then please install through your software management program (yum, apt, etc.). This is the preferred method.

If your Linux distribution does NOT carry mono-complete, or if your distribution does not have a repository, then you can download mono-complete (including -devel package) from:

http://www.go-mono.com/mono-downloads/download.html

Refer to http://www.go-mono.com or OpenSim's wiki pages for install methods used with different distributions.
Create symbolic link (a link may already exist after installation):

$ sudo ln -s /opt/novell/mono/bin/mono /usr/bin/mono

[edit] MySQL

If your Linux distribution carries MySQL5.1 in its repositories, then please install through your software management program (yum, apt, etc.). This is the preferred method.

If your Linux distribution does NOT carry MySQL, or if your distribution does not have a repository, then you can download MySQL (mysql-server or mysql-community-server) from:

http://dev.mysql.com/downloads/mysql

If installing OpenSim onto a current server, then MySQL may already be installed and started.
Start the MySQL daemon:

$ /etc/init.d/mysqld start

Alternatively, manually start or stop MySQL:

$ mysql.server start
$ mysql.server stop

[edit] Part 2: Configuring Databases

[edit] Create Grid database

$ mysql -u root --password

(or omit --password if it isn't set)

mysql> create database grid;
mysql> use grid;
mysql> grant all on grid.* to 'griduser'@'localhost' identified by 'gridpassword';
mysql> grant all on grid.* to 'griduser'@'127.0.0.1' identified by 'gridpassword';
mysql> quit

(Optionally remove single quotes from the commands above for user & address, leave the single quotes in for the password.)

Remember DB name, user name (user ID), address (DB source), and password for use with configuration files.

Note: Refer to Part 10 for steps on configuring multiple databases.

[edit] Part 3: Configuring Robust

All ./bin and ./bin/config-include references are within the "opensim-0.7.3.1" directory.

Copy Robust example file:

$ cd ./bin
$ cp Robust.ini.example Robust.ini

Open & edit Robust.ini:
Find [Database Service] section.
- Assign Grid DB ConnectionString content.
- Update data source, DB name, user ID, and password from Part 2.

Find [LoginService].
- Optionally change WelcomeMessage content.

Find [GridInfoService].
- Customize content for the grid.
- Change gridname and gridnick; optionally alter any of the URLs.
- Save & exit.

Return to ./bin and run Robust:

$ screen -S Grid mono Robust.exe
R.O.B.U.S.T.# create user

(Provide first name, last name, password, and email; remember for logging in via viewer.)

Press ctrl-a then d (to move Robust console to background without quitting).

To return to Robust console:

$ screen -r Grid

To grant god mode for a user from the Robust console:

R.O.B.U.S.T.# set user level [firstname] [lastname] 250

To set user level to normal user (this is default for all users):

R.O.B.U.S.T# set user level [firstname] [lastname] 0

Users are created in Robust; refer to OpenSim's wiki pages for setting up public user registration via web frontends.

[edit] Part 4: Configuring OpenSim

Return to ./bin and copy OpenSim example file:

$ cp OpenSim.ini.example OpenSim.ini

Open & edit OpenSim.ini:

Find [Architecture].
- Uncomment Grid line:

Include-Architecture = "config-include/Grid.ini"

Find section with permission text and adjust permissions accordingly.
Save & exit.

Change directory to ./bin/config-include and copy GridCommon example file:

$ cd ./config-include
$ cp GridCommon.ini.example GridCommon.ini

Open & edit GridCommon.ini:

Find [DatabaseService].
Comment out SQLite lines:

; SQLite
;Include-Storage = "config-include/storage/SQLiteStandalone.ini";

Uncomment MySQL lines:

; MySql
StorageProvider = "OpenSim.Data.MySQL.dll"
ConnectionString = "Data Source=localhost;Database=opensim;User ID=opensimuser;Password=opensimpassword;Old Guids=true;"

Update data source, DB name, user ID, and password from Part 2.

Note: DB configurations will be different if using multiple databases (refer to Part 10).

Find & replace all HTTP addresses with the server's address (retrieve IP address via ifconfig command).
Save & exit.

Change directory to ./bin and run OpenSim (Robust must be running in the background):

$ cd ..
$ screen -S Zone01 mono OpenSim.exe
Region (regionname) #

Running OpenSim.exe for the first time will result in the following prompts:

New Region Name – required, create a region name.

Region UUID – accept default.

Region Location – accept default.

Internal IP Address – accept default (0.0.0.0).

Internal Port – accept default (9000).

Allow Alternate Ports – accept default ("false").

External Host Name – accept default (SYSTEMIP).

New Estate Name – create an estate name.

Estate Owner First Name – enter user's first name.

Estate owner Last Name – enter user's last name.

Password – enter user's password.

Email – optionally enter user's email address.

User ID – accept default.

Press ctrl-a then d (to move OpenSim console to background without quitting).

To return to OpenSim console:

$ screen -r Zone01

Region management is handled via OpenSim. Multiple instances of OpenSim may run within Robust.

[edit] Part 5: Starting & Stopping the Grid

To start up the grid, return to ./bin, then run Robust.exe & OpenSim.exe:

$ screen -S Grid mono Robust.exe

Press ctrl-a then d

$ screen -S Zone01 mono OpenSim.exe

Press ctrl-a then d

Repeat OpenSim startup commands if there are additional instances (Zone02, Zone03, etc.).

To return to Robust console for user management:

$ screen -r Grid

(ctrl-a then d, when finished)

To return to OpenSim console for region management:

$ screen -r Zone01

(ctrl-a then d, when finished)

To shut down the grid, return to ./bin, then quit OpenSim.exe & Robust.exe:

$ screen -r Zone01
Region (regionname) # quit

Repeat OpenSim shutdown commands if there are additional instances (Zone02, Zone03, etc.).

$ screen -r Grid
R.O.B.U.S.T.# quit

[edit] Part 6: Connecting with Viewers

This part and most of Part 7 apply to all users connecting to the OpenSim environment. All other sections of this HowTo apply only to OpenSim administrator(s) and server-side functions.

[edit] Some commonly used viewers

Imprudence (has grid selector, manager, & imports): http://imprudenceviewer.org
Firestorm (has grid selector): http://www.phoenixviewer.com
Phoenix (has grid selector & manager): http://www.phoenixviewer.com
SecondLife (does not have grid selector): http://secondlife.com/support/downloads/
More viewers (including features of each): Connecting

Viewers with grid selectors provide a feature for adding grid connection criteria.

Viewers without grid selectors require the use of a command console to connect.

[edit] Connecting

[edit] Viewers with grid selectors built into them.

Add the grid to the viewer, check viewer's Preferences, then Grids:
Grid Name – give it a name.
Login URI – http://<domain or IP address> or http://<domain or IP address>:8002
Additional fields can usually be left blank.
Click Apply or OK to save the new grid.
Login with the user & password created during create user process above.

[edit] Viewers without grid selectors.

These require connecting via the computer's command console.

Windows users, press win-key + R (open Run dialog), and enter:

(viewername).exe --loginuri http://[domain name or IP address]/

or:

(viewername).exe --loginuri http://[domain name or IP address]:8002

Linux/Unix and OSX users, open a terminal, cd to viewer directory (unless it has a link), and enter:

(viewername) --loginuri http://[domain name or IP address]/

or:

(viewername) --loginuri http://[domain name or IP address]:8002

Connecting via web browser (not as common but possible), refer to: Browser_Protocol_Handler

[edit] Controlling the avatar

[edit] General movement

Walk forward/backward: W/S or ↑/↓
Turn left/right: A/D or ←/→
Run: Double-tap walk forward/backward key (some viewers: ctrl-R to turn run on/off)
Fly (on/off): F (or hold down jump to turn fly on)
Jump or fly up: E/page up
Crouch or fly down: C/page down
Sit: Right-click on self/object/ground and select "Sit" (some viewers: ctrl-S to sit/stand)
Stand: Right-click on self and select "Stand"
Teleport: Double-click anywhere within the current region (must be enabled)

[edit] Basic communication

Text chat (local): Enter key, it might be necessary to press "Esc" a couple times before "Enter".
Whisper: Shift-enter (text chat within close range).
Shout: Control-enter (text chat to a very large area of a region).
Voice chat: refer to viewer preferences for voice chat settings.

It might be better to use an external voice chat application like Mumble, Skype, or TeamSpeak.

Voice chat applications that can be integrated into OpenSim: Mumble, Vivox, and Freeswitch.

Some voice chat applications may require installing add-ons to either the viewer and/or server.

[edit] Basic world navigation

Refer to viewer menus/website for specific keys/buttons that open the following.
Mini-map: when enabled, this displays the current region in the corner of the screen.
Map: when opened, this displays the grid – all of the world's regions – in a larger window.
Double-click somewhere within the Map to teleport to another region.

[edit] Defining the world

The world that users access consists of the following.

Grid: the entire virtual world or universe contained within the server, viewable via Map with the viewer.
Estate: one or more regions owned by a resident/group, size ranges from 16m² to a full region(s).
Region: one square on the Map, totaling 65,536m² in-world sim space with a usable height of 4,096m.*
Parcel: one section within a region owned by a resident/group, size ranges from 16m² to a full region.
Sim: a generic term, from simulator, which has been used in reference to any of the terms defined above.

*The size of one region is equal to a grand total of 268,435,456m³ (256m x 256m x 4096m).

[edit] Objects & Avatars

Object sizes generally range from 0.01m³ to 256m³ (unless size limitations are set within the server).
Avatar, aka resident, heights generally range from 1.25m to 2.95m** (unless using objects & alpha layers).

**Approximately 4'1" to 9'8".

[edit] Part 7: Building & Importing

[edit] Creating regions within a world (administrator(s) only)

Change directory to ./bin/Regions and edit Regions.ini:

There should initially be 1 default region.

Copy/paste the content of 1^st region directly below.

Edit the new region:

[Region] – give it a new name

RegionUUID – alter only 1 digit in this, one number higher works fine

Location – the X,Y Map coordinate in the Grid, change X and/or Y***

InternalAddress – leave this at the default 0.0.0.0

InternalPort – alter by 1 digit, increase by one number works fine

AllowAlternatePorts – leave this default (as "False")

ExternalHostName – use server's IP address (retrieve via ifconfig) (domain name may not work)

If the X,Y Map coordinates between 2 or more regions are adjacent to one another, then those regions will be adjacent in-world, and users can cross between regions without teleporting.

Note: X,Y Map coordinates only apply to region locations on the grid, as designated within Regions.ini file(s), they should not be confused with the in-world X,Y,Z coordinates accessible by users.

***A layout of all regions on the grid can be initially created and organized in a spreadsheet document to assist with developing the grid's world map.

Refer to OpenSim website for details pertaining to:

Estate, region, & parcel ownership.
Permissions within regions (access, fly/no-fly, building, scripting, etc.).
Terrains (land/water), environments (sky/backdrop), physics, wind, etc.
(Also see http://westwood.wikispace.com or search similar sites for Terraforming terrains.)

[edit] Building & editing objects within a world (all users)

If the sim that the avatar is on has building permissions enabled, then: Right-click on the land near the avatar & select "Build" or select Build from menu.

Alternatively, select "Edit" on a current object (must own object or have edit permissions). Experiment with all of the features in the window that opens up.

Be sure to "Take" temporary objects after reaching a stopping point with the builds to avoid littering the world.

Refer to this site or search online for other sites with more information on building & editing objects:

Objects – http://westwood.wikispaces.com/Creating+Objects+in+Open+Sim
Buildings – http://westwood.wikispaces.com/Creating+Buildings+in+Open+Sim

[edit] Customizing avatars (all users)

Open Inventory (ctrl-I or click from menu) for clothes and more (objects, scripts, etc.).

Select "wear" on clothes and avatar items from Inventory.

It might be necessary to create new shape, skin, eyes, etc. then wear them.

After wearing items, right click on avatar and select "Appearance..." or "Edit Appearance". Experiment with all the of the features to alter the avatar.

Also, refer to this site or search online for a similar website: http://westwood.wikispaces.com/Modifying+Clothes+and+Appearance+in+Open+Sim

[edit] Importing inventory (all users)

The Imprudence viewer, or a viewer with a compatible importer tool is required to import/export objects, avatars, and other inventory items to/from the world:

Refer to Linda Kellie website for several free importable creations:

http://www.lindakellie.com

The Linda Kellie website includes such items as: animals, animations, attachments, buildings, clothing, food & drinks, furniture, hair, holiday items, IAR files, OARs, plants, sculpts, skins, terrains, and textures.

[edit] Part 8: Additional Administrative Options

[edit] In-world physics

Change directory to ./bin in OpenSim.

$ cp OpenSimDefaults.ini OpenSimDefaults_BACKUP.ini

Open & edit OpenSimDefaults.ini.
Find [ODEPhysicsSettings].
Adjust in-world physics (gravity, speed of movement (walk, run, flight), etc.)
Save & exit.

If it breaks your sim, make more adjustments or revert to the backup.

[edit] Refer to Main_Page for the following information

Backups
Server Commands, highly useful commands
OpenDynamicsEngine and increasing the stack reserve level
NAT/loopback, if server has a router
Working with firewalls
Loading OARs (OpenSim_Archives)
Configuring permissions
Selling parcels via landtool.php
Mapgenerator, also edit MapImageModule in OpenSim.ini
User levels.

From Robust console: set user level [firstname] [lastname] [level]

"god_not" = value 0 (normal users)

"god_like" = value 1 (rename objs without mod perms)

"god_customer_service" = value 100 (char.geom., take copy, owner, linden, public land)

"god_liaison" = value 150 (enable land auction)

"god_full" = value 200 (no apparent difference from god_liaison)

"god_maintenance" = value 250 (no apparent difference from god_full)

"Set" command (from console):

"region master" (also called "master avatar" or "region owner")

"administrator"

"estate owner"

"god"

"estate manager"

"parcel owner"

"parcels managers"

"object manager"

Configuring region modules : IRC, freeswitch, offline messaging, profiles, groups
Config webpages/server (webserver within Opensim & external pages)
Enabling Groupss, needed to allow shared building
GroupModule, "XmlRpcGroupsServer" (https://github.com)

Configuring simulator parameters
Upgrading (from 0.7.3.1 to newer)
Network settings
Database queries (Useful_Queries)
Logging
Monitoring
Automated tasks
Remote console
Tweak performance & scale
Console-less OpenSim
NPCs, aka bots
And a lot more: Integration, Remoteadmin, Authintegration, Usermanipulation,Known web interfaces within opensim, Feature matrix, Scripting documentation, Opensim archives, Opensimulator inventory archives, Custom libraries, IRCbridgemodule, Hypergrid, Gridinfo, Physicsengines, Autobackup, Freeswitch module, Mumble, Enabling groups, Jsonstore module, Tutorials.

[edit] Part 9: Links

Troubleshooting
FAQ
Tips (terraforming/loading/importing)
NewWorld Studio (alternate install method):

http://code.google.com/p/newworldstudio/

or

http://www.newworldstudio.org/site/en

Viewers, projects, add-ons:

Related_Software

Connecting

Linda Kellie imports:

http://www.lindakellie.com/

[edit] Part 10: Appendix

[edit] Creating & configuring multiple databases

Create Grid DB and assign to Robust.ini as described in Parts 2 & 3.

[edit] Create Estate & Zone DBs

$ mysql -u root --password

(or omit --password if it isn't set)

mysql> create database estate;
mysql> use estate;
mysql> grant all on estate.* to 'estateuser'@'localhost' identified by 'estatepassword';
mysql> grant all on estate.* to 'estateuser'@'127.0.0.1' identified by 'estatepassword';
mysql> create database zone01;
mysql> use zone01;
mysql> grant all on zone01.* to 'zone01user'@'localhost' identified by 'zone01password';
mysql> grant all on zone01.* to 'zone01user'@'127.0.0.1' identified by 'zone01password';

(Repeat create/use/grant commands for additional zone02, zone03, etc.)

mysql> quit

[edit] Assign Estate & Zone DBs to GridCommon.ini

Follow the steps described in Part 4, alter the GridCommon.ini DB configuration with the following.

Open & edit GridCommon.ini:
Find [DatabaseServices].
Uncomment "EstateConnectionString" line:

EstateConnectionString = "Data Source=localhost;Database=opensim;User ID=opensim;Password=***;"

Update data source, DB name, user ID, and password with estate DB content.
Copy & paste "ConnectionString" line for each zone.
Update data source, DB name, user ID, and password with zone01, zone02, etc. DB content.
Save & exit.

This arrangement consists of the following:

1 Grid DB for Robust.exe (grid)
1 Estate DB for all estates (estate)
1 Zone DB for each instance of OpenSim.exe (zone01, zone02, etc.)

If running only one instance of OpenSim.exe and using multiple databases, then only one zone DB is necessary in coordination with the Grid DB. The Estate DB is optional. The OpenSim.exe application can run one or multiple simultaneous times on the same computer that is running Robust.exe and/or on different computers at other locations, in which case multiple zone DBs could be used. Refer to OpenSim's wiki pages for details on configuring OpenSim.exe applications to connect from external hosts to a primary server that is running the grid (Robust.exe). Note that if external hosts (instances of OpenSim.exe) go offline then their regions will not be accessible via the grid.

The term "zone" refers to one running instance of OpenSim.exe that contains one or more regions.

@@ Line 1: / Line 1: @@
+<div style="background-color:#FFA500; padding:10px; padding-bottom:5px; border: 1px #FF544F solid">
+'''This article was last updated in 2014, since then a lot of things have changed and information is likely no longer accurate, proceed with caution!'''
+</div>
 ='''O'''pen'''S'''im '''H'''ow'''T'''o=
-<center>''Configuring a Grid''</center>
+<center>'''''Configuring a Grid'''''</center>
@@ Line 27: / Line 31: @@
 ===Required software===
 * OpenSim (v0.7.3.1 or newer)
-* mono-complete (v2.4.3 or newer)
+* mono-complete (v2.4.3 or newer, '''important''': mono must be the complete package plus -devel)
-* MySQL (v5.1 or newer)
+* MySQL (v5.1 or newer, slightly older versions might be compatible)
 ===OpenSim===
 * Download OpenSim here: [[Download]]
@@ Line 66: / Line 71: @@
   mysql> grant all on grid.* to 'griduser'@'127.0.0.1' identified by 'gridpassword';
   mysql> quit
-(Remove single quotes from the commands above after designating user, address, & password.)
+(Optionally remove single quotes from the commands above for user & address, leave the single quotes in for the password.)
 Remember DB name, user name (user ID), address (DB source), and password for use with configuration files.
@@ Line 96: / Line 101: @@
 *Return to ./bin and run Robust:
-  $ mono Robust.exe
+  $ screen -S Grid mono Robust.exe
   R.O.B.U.S.T.# create user
 :(Provide first name, last name, password, and email; remember for logging in via viewer.)
-  R.O.B.U.S.T.# quit
+*Press ctrl-a then d (to move Robust console to background without quitting).
+*To return to Robust console:
+  $ screen -r Grid
 *To grant god mode for a user from the Robust console:
@@ Line 111: / Line 119: @@
 ----
 == Part 4: Configuring OpenSim ==
 Return to ./bin and copy OpenSim example file:
@@ Line 141: / Line 150: @@
 : Note: DB configurations will be different if using multiple databases (refer to Part 10).
-* Find & replace all HTTP addresses with the server's address.
+* Find & replace all HTTP addresses with the server's address (retrieve IP address via ifconfig command).
 * Save & exit.
-Change directory to ./bin and run OpenSim:
+Change directory to ./bin and run OpenSim (Robust must be running in the background):
   $ cd ..
-  $ mono OpenSim.exe
+  $ screen -S Zone01 mono OpenSim.exe
   Region (regionname) #
 : Running OpenSim.exe for the first time will result in the following prompts:
-: '''New Region Name''' – required, create a region name; if it asks to join estate, say no (default).
+: '''New Region Name''' – required, create a region name.
 : '''Region UUID''' – accept default.
 : '''Region Location''' – accept default.
@@ Line 157: / Line 166: @@
 : '''Allow Alternate Ports''' – accept default ("false").
 : '''External Host Name''' – accept default (SYSTEMIP).
- Region (regionname) # quit
+: '''New Estate Name''' – create an estate name.
+: '''Estate Owner First Name''' – enter user's first name.
+: '''Estate owner Last Name''' – enter user's last name.
+: '''Password''' – enter user's password.
+: '''Email''' – optionally enter user's email address.
+: '''User ID''' – accept default.
+* Press ctrl-a then d (to move OpenSim console to background without quitting).
+* To return to OpenSim console:
+ $ screen -r Zone01
 Region management is handled via OpenSim. Multiple instances of OpenSim may run within Robust.
@@ Line 163: / Line 185: @@
 ----
-=== Part 5: Running Robust & OpenSim ===
-*Return to ./bin, run Robust.exe & OpenSim.exe:
+== Part 5: Starting & Stopping the Grid ==
+*To start up the grid, return to ./bin, then run Robust.exe & OpenSim.exe:
   $ screen -S Grid mono Robust.exe
 :Press ctrl-a then d
   $ screen -S Zone01 mono OpenSim.exe
 :Press ctrl-a then d
+:Repeat OpenSim startup commands if there are additional instances (Zone02, Zone03, etc.).
@@ Line 179: / Line 203: @@
   $ screen -r Zone01
 :(ctrl-a then d, when finished)
+*To shut down the grid, return to ./bin, then quit OpenSim.exe & Robust.exe:
+ $ screen -r Zone01
+ Region (regionname) # quit
+:Repeat OpenSim shutdown commands if there are additional instances (Zone02, Zone03, etc.).
+ $ screen -r Grid
+ R.O.B.U.S.T.# quit
@@ Line 376: / Line 408: @@
 * [[Configuration|Configuring region modules]] : IRC, freeswitch, offline messaging, profiles, groups
 * Config webpages/server (webserver within Opensim & external pages)
-* [[Group]]s, needed to allow shared building
+* [[Enabling Groups]]s, needed to allow shared building
 * GroupModule, "XmlRpcGroupsServer" ([https://github.com/mcortez/flotsam/tree/master/flotsam/Servers/XmlRpcGroupsServer/ https://github.com])

Views

OSHT

From OpenSimulator