Revision as of 16:01, 20 June 2012

OpenSim HowTo

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

Part 1: Downloads & Dependencies

Required software

• OpenSim (v0.7.3.1 or newer)
• mono-complete (v2.4.3 or newer)
• MySQL (v5.1 or newer)

OpenSim

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

$ tar xvzf opensim-0.7.3.1.tar.gz

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

MySQL

• If your Linux distribution carries MySQL5.1 in its repositories, then please install trough 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 on a current server, then MySQL may already be installed and started/running.
• Start the MySQL daemon:

$ /etc/init.d/mysqld start

• Alternatively, manually start or stop MySQL:

$ mysql.server start
$ mysql.server stop

Part 2: Configuring Databases

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

(Remove single quotes from the commands above after designating user, address, & 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.

• 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:

$ 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

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

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.
• Save & exit.

Change directory to ./bin and run OpenSim:

$ cd ..
$ 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).

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

Region (regionname) # quit

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

Part 5: Running Robust & OpenSim

• Return to ./bin, 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

• 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)

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.

Connecting

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.

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

• OSX users, refer to OpenSim website.

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

Controlling the avatar

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

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

Part 7: Building & Importing

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

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:

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

Part 8: Additional Administrative Options

In-world physics

• Change directory to ./bin in OpenSim.

$ cp OpenSimDefaults.ini OpenSimDefaults_BACKUP.ini

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

Refer to Main_Page for information about:

• 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)
• Groups, 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/

Part 10: Appendix

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.

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