FAQ

A list of frequently asked questions. Please add anything you think is reasonable here.

= What is OpenSim? =

OpenSim is a platform for operating a virtual world, and supports multiple independent regions connecting to a single centralized grid. This is somewhat similar to the web, where anyone can run their own web server, tied together through the internet. It can also be used to create a private grid, analogous to a private intranet.

What is a region?
A region is what you see when you log into OpenSim. It is the physical place (well, virtually physical) where avatars move and interact. It is a square patch of land which may contain an island, mountains, a plain, buildings, etc., or just an ocean.

What is the grid?
The grid is the level that organizes the regions and their positions in the world, and handles things that need to exist across regions, such as a user's inventory. You can think of it as similar to the world map.

What does ... mean?
See OpenSim:TechRef for definitions of some terms commonly used in OpenSim.

= Building OpenSim =

I can't find any build files or solution files

 * If you're on Windows, run runprebuild.bat - on Linux/Mac/FreeBSD, run runprebuild.sh

VS2005 won't open the .sln file

 * Try running VS2005 C#. You are probably running VS2005 C++. This is a C# project.

= Running OpenSim =

Running OpenSim.exe from a Cygwin shell has access denied for some dll's

 * Do a 'cd bin' followed by 'chmod a+x *' to make all dll files executable.

I cannot start my sim

 * See OpenSim: Running.

= Configuring OpenSim =

First, read OpenSim: Configuration.

Where can I get a new UUID for my sim config?
Use 'uuidgen' or generate one on the uuidgen webpage.

Can I run multiple regions with OpenSim?
Yes. To do this add another xml file to bin/Regions. You need to create a new 'sim_UUID' (see above) and change the 'sim_name', 'internal_ip_port', 'sim_location_x' and 'sim_location_y' (and anything else you wish to change). The script share/regions/make.php may be useful for generating region files automatically. Once the new region files have been added to bin/Regions, restart OpenSim.

Note that sim_location_x</tt> and sim_location_y</tt> should be in adjacent regions, so you will be able to run back and forth between regions.


 * See OpenSim: Configuration.

How do I enable prim storage?
storage_plugin = OpenSim.DataStore.MonoSqlite.dll or storage_plugin = OpenSim.Framework.Data.MySQL.dll
 * In the OpenSim.ini</tt> file, change the storage_plugin</tt> entry to

You will also need to provide connection details in a storage_connection_string</tt> attribute - see the OpenSim.ini.example</tt> file in the bin directory of the OpenSim package for more information.

There are a bunch of textures in the library, but they are all 0x0? What's wrong?
To enable these extra textures for your use, you must delete your regionassets.yap</tt> file, and restart your sim. WARNING: IF YOU DO THIS, YOU WILL LOSE ANY ASSETS (textures, scripts, animations, etc) THAT YOU HAVE UPLOADED!

What databases can be used with OpenSim?
For running in standalone mode, OpenSim provides database plugins for both sqlite and MySQL. There is also an MSSQL plugin, though this has not been thoroughly tested. Sqlite requires no user configuration to set up while MySQL requires some minimal user configuration (see mysql-config).

Running in grid mode is usually done using the MySQL database. Sqlite and MSSQL may work but have not been thoroughly tested.

Can I export all my prims, for safe keeping?
Yes. From the console type: save-xml [filename]

You can later load those prims with: load-xml [filename]

This is also a good way to dump and clone prims from one OpenSim server to another.

= Something Has Gone Wrong! =

I get errors concerning 'owner_uuid' when starting up my grid after updating from svn beyond r3254
When updating to recent revisions after r3254, we are now using the unused owner_uuid. There are some grids whose mysql tables were created during a time when this field was inadvertently removed from the .sql script that initializes the regions table. Logging in to your mysql instance and executing this SQL query to add the missing owner_uuid should solve this issue:

alter table `regions` add column `owner_uuid` varchar(36) default '00000000-0000-0000-0000-000000000000' not null, comment 'Rev.2';

The punctuation around regions and owner_uuid is "grave accent". The punctuation around the default value and the comment is the single quote. The "grave accent" is the one generally to the left of the One button, under the tilde and the single-quote, is, well, underneath the double quote. I think this matters to mysql.

I get a timeout during region handshake

 * Do you have the correct IP in your Regions\* config files?
 * Do you have multiple interfaces on the server running OpenSim? OpenSim will not bind outgoing UDP packets to a specific IP, its default IP to reach you will be what the Region answers UDP with. If you have configured the region for another IP you will get a timeout during connect.

I cannot connect to my OpenSim

 * See OpenSim: Connecting.

I can connect but cannot move
If the client connects but the avatar can only spin in place and not move, then the sim is not correctly configured. It completed the initial login function, but packets are not being exchanged between the client and the sim, probably due to a network configuration error on the sim.


 * See OpenSim: Configuration.

From time to time my Avatar seems to get stuck
Right now there is a bottle neck when syncing prims off to the database. This will cause small (5 - 10 second) apparent hangs of the Avatar, but it will recover fine once the data is synced. It is a known issue based on legacy architecture of some of the data storage code. We hope this will be removed soon.

I have problems with viewing the worldmap

 * This may happen when running OpenSim on a Linux server, both in grid or standalone mode.
 * Symptoms: when opening the worldmap window in the SL-viewer, the sims are not displayed grahically in the worldmap, the server console shows some error related to openjpeg, the current session freezes...
 * Reason: your svn source trunk does not have the correct (or whatever...) libopenjpeg-libsl</tt> library.
 * Other reason: the file "defaultstripe.png" does not exists in the same OpenSim folder, or is corrupted.
 * Solution: get the newest code from libsecondlife (svn co svn://opensecondlife.org/libsl/trunk</tt>), 'make</tt>' manually in the subdir openjpeg-libsl</tt>, and copy the resulting libopenjpeg-libsl-2.1.2.0.so</tt> into your OpenSim bin</tt> subdir, overwriting the existing one.
 * Recompile & restart OpenSim.

= Exceptions on the Console = This is a list of Exceptions that you may see on the console, what they mean, and if they are a problem.

System.DllNotFoundException: ./libopenjpeg-libsl-2.1.2.0.so
Failed generating terrain map: System.DllNotFoundException: ./libopenjpeg-libsl-2.1.2.0.so at (wrapper managed-to-native) OpenJPEGNet.OpenJPEG:LibslAllocDecoded OpenJPEGNet.OpenJPEG/LibslImage&) at OpenJPEGNet.OpenJPEG.Encode (System.Byte[] decoded, Int32 width, Int32 height, Int32 components, Boolean lossless) [0x00000] at OpenJPEGNet.OpenJPEG.EncodeFromImage (System.Drawing.Bitmap bitmap, Boolean lossless) [0x00000] at OpenSim.Region.Terrain.TerrainEngine.ExportJpegImage (System.String gradientmap) [0x00000]

You are on Linux, and the native lib libopenjpeg-libsl-2.1.2.0.so is not compatible with your system for one of the following reasons:
 * You have an old processor (libopenjpeg has been compiled with optimizations)
 * You are running in 64bit mode (none of the native libs are built for 64bit)

You can rebuild your own libopenjpeg from source, or run in a compatible environment. You can do this by: svn co svn://opensecondlife.org/libsl/trunk libsl cd libsl/openjpeg-libsl/ make

then copy libopenjpeg-libsl-2.1.2.0.so into OpenSim bin-folder.

= OpenSim in the Wild =

Are there test servers running OpenSim I can connect to?
Yes. Check out http://www.deepgrid.com, http://osgrid.org

There are also often many private servers up for testing. Hang out on the IRC channel (Freenode #opensim), and troll for URI's.

Can I teleport from the Linden Lab Second Life grid to my Sim?
No, OpenSim islands cannot connect to the Linden Lab grid.

= Terrain Tidbits =

What programs can I use to create terrains for OpenSim?
If you are after simple terrain files (jpg, gif, etc), you can use Photoshop or any number of freeware programs, like Gimp. If you want more complex terrains, you will need programs that output to standard 3d raw format (aka r32 or r64). L3DT and Terragen are two of the top commercial programs for this. (anyone know of a freeware one?), or you could, with some practice, use Blender. The free version of L3DT can make terrains up to 2048x2048 in size, or 8x8 regions.

You can use `terrain load IMG yourfile.png` to load greyscale PNG files. Remember to use something like `terrain rescale 0 25` to make it visible.

Here is some info on Using L3DT to make a terrain.

You can also use http://lab.parkstudio.ru/terra/ if you know a bit about heightmaps and how they work. Just set the custom landscape texture gradient to pure black and pure white and turn off water.

And here are some Free Terrains that you can use. Enjoy!

Where do I put the files for my terrains?
This one is actually pretty simple, but first the 'hard' answer: anywhere in the PATH will work. Lost? yeah, I was too, so... just drop the file into the bin</tt> directory (right where your OpenSim.exe</tt> file is).

How do I change the terrain for a group of sims?
First, the file must be in f32 (or f64?) format. This is easy to do with L3DT's export feature. (Use the RAW format and set the options to Y flipped = true</tt> and at the bottom, change it to read 'float' instead of 'ushort'). It also needs to be a file that will cover each sim in a 256x256 layer (so, for 2x2 regions, you need a 512x512 file).

Then, once you have it saved, on the <tt>OpenSim.exe</tt> console, type in:

terrain load-tile f32 <image X> <bottomleftsim X>

For example, I run a square of 4 sims in a 2x2 pattern. I started my sim placement at 0, 0 and ended at 1, 1. my line reads:

terrain load-tile f32 simalpha.raw 512 512 0 0

Next, before you log in, you may want to go to type in:

terrain multiply 0.4

This should scale it down from the nearly 300 meters altitude I ran into to something a little more reasonable for the minimap.

How do I load a terrain file on startup?
Edit the file <tt>startup_commands.txt</tt> in the bin directory and add the above commands "<tt>terrain load-tile ...</tt>" and "<tt>terrain multiply ...</tt>" one per line.

Terrain Tidbits brought to you by Tilde, with a few questions in IRC :) - Tilde 10:32, 15 August 2007 (PDT)

How do I import into OpenSim the terrain shape of my Second Life sim?
First, assure you are in the right region if you have more than one, by using:

change-region

Then use the command (depending on the filetype (F32 etc), RAW can also be used in place of here)

terrain load

Watch this video for a step-by-step tutorial.

Other useless or usefull info depending on who reads it
example: 1) 0,0,0  2) 223, 233, 233   3) 255, 255, 255
 * I found out that each point on the grey scale (0 to 255) equals approximately .23 to .25 meters in terrain height. - CharlieO
 * Also for those who want to manually edit a png file, you need at minimum 3 different shades of grey. and one has to be drastically different than the other 2 in order to have the height show correctly. - CharlieO

How do I isolate and delete a users Trash items in my mySQL database?
1. Locate the avatars UUID you wish to find the trash items of in the users table

This query will locate a specified users UUID: (replace User/Test with username/lastname) SELECT `UUID` FROM `users` WHERE `username` LIKE 'User' AND `lastname` LIKE 'Test' LIMIT 0, 30 2. Use the avatars UUID to search the field_name AgentID in the inventoryFolders table, using Trash as the folder name

This query will locate the users Trash folder entries: (replace 00000000-0000-0000-0000-000000000000 with UUID of user) SELECT `folderID` FROM `inventoryfolders` WHERE `agentID` LIKE '00000000-0000-0000-0000-000000000000' AND `folderName` LIKE 'Trash' LIMIT 0, 30 3. Use the folderID UUID obtained in the last query to find all of the trash items in the inventoryitems table

This query will locate the trash items of the avatar in question, you can then delete them once you have isolated them. SELECT * FROM `inventoryitems` WHERE `parentFolderID` LIKE '00000000-0000-0000-0000-000000000000' LIMIT 0, 30  NOTE:  These steps will not remove the associated assets from the assets table, just the items in the inventory inventoryitems table.

How do I isolate and resolve duplicate inventory folder entries my mySQL database?
= In World Questions =

Does in world scripting work yet?
Not fully implemented, but there is a lot of work going on here. Please see LSL Status for the latest info.

Why do I walk through objects?
Basicphysics doesn't support collisions between objects (just between you and the ground). There is active work on other physics engines for OpenSim, but these are quite experimental at this point, so not considered supported.

Can I customize my avatar?
Yes. In order to do this:
 * Click the Inventory Button
 * Create -> New Clothes -> Shirt, Pants, etc
 * Create -> New Body Parts -> Hair, Shape, etc
 * Edit those from your inventory
 * Wear them

Your avatar doesn't always face a nice direction for doing this, so you'll need to use the camera operations to see your face for some of the modifications. This is a known issue, will be fixed in the future.

Also, you'll need to rewear you parts once you first join the environment. Right now default appearance is always "Ruth".

= Grid Mode = Note: Grid Mode isn't officially supported yet. As such, you are pretty much on your own if you are trying to get OpenSim up and running in Grid Mode.

I start the sim and it doesn't connect to any grid
When OpenSim is first started, it needs configuration.


 * See OpenSim: Configuration.

I start the OpenSim.Grid.UserServer.exe and it gives an error
If this error is access denied for <tt>username@localhost</tt>, the mysql database is not set up.

It will print some text and wait for input - either an enter to accept a default value, or another value you can supply.


 * See OpenSim: Configuration.

I want to run my own Local Grid but one or more servers fail to start

 * Be sure that you're able to start <tt>OpenSim.exe</tt> alone, in Standalone mode, and to be able to login.
 * Start the servers in the correct UGAS order and answer the questions as recommended (see OpenSim: Configuration).
 * Set all the external URI's to the correct IP: 127.0.0.1 if running on your local machine, or aaa.bbb.ccc.ddd if running on a remote server.
 * Check again all the <tt>*.xml</tt> configuration files for any wrong settings or typing errors...!
 * Don't forget to connect with your SL-viewer to port 8002 (Grid User-Server) instead of 9000 (Standalone OpenSim-Server).
 * Delete all <tt>*.xml</tt> and <tt>*.yap</tt> files in the <tt>bin</tt> directory if you want to run a full reconfiguration again.

After the shiny new grid is running, what is next?

 * Make sure one can stop/restart UGA &S (sims). Check out any ordering issues of stop/restart UGA w/o stop/restart sim(s).
 * Make sure one can add/delete both a region and a user from the database.
 * Make sure it runs overnight and check it each morning by logging into 1 or 2 key sims.
 * '<tt>tail -f userserver.log</tt>' and watch/understand the login process.
 * Make sure when you logoff your system, you can log back on and get control of the UGAS consoles.

I get a bunch of asset not found errors, while connected to a online grid, and my inventory doesn't seem to work right

 * Make sure your opensim.ini has '     asset_database = "grid"      ' otherwise it will not work correctly.

= How to ask for help =

Before asking for help...

 * Search the wiki and web before asking for help.
 * Check your configuration files for any obvious defects.
 * Check that you're starting up the processes correctly.
 * See OpenSim: Install.
 * See OpenSim: Configuration.
 * See OpenSim: Running.
 * See OpenSim: Connecting.

Asking in IRC
IRC channels are <tt>#opensim</tt> and <tt>#opensim-dev</tt> on Freenode. Approach them in that order :) Please be courteous and remember that the developers and anyone else assisting you are volunteers there.


 * Don't ask to ask, just ask.
 * Phrase your question in the form of a question.
 * Be specific.
 * Explain the problem.
 * Describe how to reproduce the problem.
 * If you need to paste configuration files or error messages, please paste to pastebin then send the link in the IRC channel.

After you get help

 * If no-one can help you, please submit a bug.
 * If someone does help you, please document the problem and fix on the wiki on this page.