OSHT

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!

=OpenSim HowTo=

Configuring a Grid

rev.20120620

compiled by "Zylek" ([mailto:zy.zylek@gmail.com 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!

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)

OpenSim
$ tar xvzf opensim-0.7.3.1.tar.gz
 * Download OpenSim here: Download
 * Extract contents to an appropriate directory:

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

$ sudo ln -s /opt/novell/mono/bin/mono /usr/bin/mono
 * 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):

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

$ /etc/init.d/mysqld start $ mysql.server start $ mysql.server stop
 * If installing OpenSim onto a current server, then MySQL may already be installed and started.
 * Start the MySQL daemon:
 * Alternatively, manually start or stop MySQL:

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.

Part 3: Configuring Robust
All ./bin and ./bin/config-include references are within the "opensim-0.7.3.1" directory.

$ cd ./bin $ cp Robust.ini.example Robust.ini
 * Copy Robust example file:


 * 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.

$ screen -S Grid mono Robust.exe R.O.B.U.S.T.# create user
 * Return to ./bin and run Robust:
 * (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).

$ screen -r Grid
 * To return to Robust console:

R.O.B.U.S.T.# set user level [firstname] [lastname] 250
 * To grant god mode for a user from the Robust console:

R.O.B.U.S.T# set user level [firstname] [lastname] 0
 * To set user level to normal user (this is default for all users):

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

Part 4: Configuring OpenSim
Return to ./bin and copy OpenSim example file: $ cp OpenSim.ini.example OpenSim.ini

Open & edit OpenSim.ini: Include-Architecture = "config-include/Grid.ini"
 * Find [Architecture].
 * Uncomment Grid line:
 * 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: ; SQLite ;Include-Storage = "config-include/storage/SQLiteStandalone.ini"; ; MySql StorageProvider = "OpenSim.Data.MySQL.dll" ConnectionString = "Data Source=localhost;Database=opensim;User ID=opensimuser;Password=opensimpassword;Old Guids=true;"
 * Find [DatabaseService].
 * Comment out SQLite lines:
 * Uncomment MySQL lines:
 * 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.

Part 5: Starting & Stopping the Grid
$ screen -S Grid mono Robust.exe
 * To start up the grid, return to ./bin, then run Robust.exe & OpenSim.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.).

$ screen -r Grid
 * To return to Robust console for user management:
 * (ctrl-a then d, when finished)

$ screen -r Zone01
 * To return to OpenSim console for region management:
 * (ctrl-a then d, when finished)

$ screen -r Zone01 Region (regionname) # quit
 * To shut down the grid, return to ./bin, then quit OpenSim.exe & Robust.exe:
 * Repeat OpenSim shutdown commands if there are additional instances (Zone02, Zone03, etc.).

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

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.

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.

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://  or  http://: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.

Viewers without grid selectors.
These require connecting via the computer's command console. (viewername).exe --loginuri http://[domain name or IP address]/ or: (viewername).exe --loginuri http://[domain name or IP address]:8002
 * Windows users, press win-key + R (open Run dialog), and enter:

(viewername) --loginuri http://[domain name or IP address]/ or: (viewername) --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:


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

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)

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.

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.

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 16m2 to a full region(s).
 * Region: one square on the Map, totaling 65,536m2 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 16m2 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,456m3 (256m x 256m x 4096m).

Objects & Avatars

 * Object sizes generally range from 0.01m3 to 256m3 (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".

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 1st 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.)

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

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

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:
 * http://wiki.kokuaviewer.org/wiki/Downloads
 * http://www.singularityviewer.org/downloads

Refer to Linda Kellie website for several free importable creations: 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.
 * http://www.lindakellie.com

In-world physics
$ cp OpenSimDefaults.ini OpenSimDefaults_BACKUP.ini If it breaks your sim, make more adjustments or revert to the backup.
 * Change directory to ./bin in OpenSim.
 * Open & edit OpenSimDefaults.ini.
 * Find [ODEPhysicsSettings].
 * Adjust in-world physics (gravity, speed of movement (walk, run, flight), etc.)
 * Save & exit.

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.

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/

Creating & configuring multiple databases

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

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

Assign Estate & Zone DBs to GridCommon.ini
Follow the steps described in Part 4, alter the GridCommon.ini DB configuration with the following. EstateConnectionString = "Data Source=localhost;Database=opensim;User ID=opensim;Password=***;"
 * Open & edit GridCommon.ini:
 * Find [DatabaseServices].
 * Uncomment "EstateConnectionString" line:
 * 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.