Updated – Opensim Install and Configuration Tutorial

This tutorial assumes that you’ve already gone through the Updated – MySQL Installation Guide first, and have the MySQL database running on your machine. If you haven’t, I suggest you go to the main page and look up that article!

One more caveat: The window installers always lag the current development versions by a bit. You are in better shape if you run on linux, which is why I made a Virtual Machine that is already configured using Debian 5 that you can download (and please seed if you can!).

So lets dive in, shall we?

We’ll need the most current binary from the opensimulator website, so navigate with your favorite browser here:

Next, click on the ‘Download’ icon near the top. You’ll also want to bookmark this site, as it has some answers to technical questions and requirements.

You’ll see a section once the page loads, called “Binary Packages”. You’ll want to download the .zip archive, since windows understands what to do with .zip files (or if you have installed a utility that does – same difference).

As of this writing, the version is 0.6.8 – right-click on the link and select “Save Link As”. Save the zip file where you can find it easily later. You’ll be extracting all the files on to your hard drive in a bit.

Get up, and take a break – depending on your connection, this will take a few minutes.

Once it is done, navigate to where you saved the file. Extract the file to a folder of your choice. I chose to make a folder called “opensim” on my C: drive.

You’ll see a main folder called “opensim-0.6.8.-binaries” once it is done. That is nice, but I’d like it all to be under a one thing, so lets cut-and-paste the folders so they are all under the “opensim” folder. The end result will look like this:

Now, to tweak some configuration files. You’ll want to keep the zip file around, just in case you make a mistake. I’m going to reference my folder structure here, so if you made any changes, substitute in your head. We’re now going to navigate to the opensim\bin directory.

Depending on how you have your options set in windows, you’ll see something like this:

The file we’re interested in right now is opensim.ini – find it, and open it up in either notepad or wordpad to make some changes.

Since we have our database installed, we need to make some changes to point opensim to that database. I hope you have your database password memorized, you’re going to need it here.

Scroll down and find the section “STORAGE” in opensim.ini

By default, opensim uses SQLite. But we’re not going to use that, so we need to change things. First, put semi-colons in front of the following, to comment them out. This will tell opensim we aren’t using these lines in our configuration.

Below those lines is the MySQL configuration lines. We need to uncomment these, so remove the semi-colons. Also, we need to change the connection string so it looks like this when you’re done. (Remember, put in YOUR password to the database where I’ve put PASSWORD.) One other note, it is totally possible to access the database using another user other than root, but frankly – I’m not going to get into that. For expediency sake, just use what I have here in the interim.

Now, lets go to the section called “Standalone”. You’ll have to scroll a bit to find it. Here, you can change the welcome message that you’ll get when you log in to your server, and the inventory database configuration.

We need to change the “Inventory database provider” and “Inventory Source” to point to our MySQL database. Change the following so it looks like this (remember, insert YOUR database password where PASSWORD is):

Okay, now we’ll have to do the same with the “User Data Database provider” section below it. Change the configuration so it looks like this, inserting your database password:

Make sure to save your progress.

This part has changed from the last time I wrote the guide, there is another configuration file to edit in a different folder. Make sure your work is saved, and navigate to the following – opensim\bin\config-include.

The file we’re looking for is “StandaloneCommon.ini.example”. We’re going to save this under a different name so we don’t alter the original. Open the file up in either notepad or wordpad.

The first thing we’re going to do, is save this as “StandaloneCommon.ini” under the same directory. Do that now.

Good, now the first section you see should be familiar – “DatabaseService”. We’ll need to change the database provider and connection strings. Here’s what they should look like after you are done (after inserting your database password at PASSWORD, of course):

Save your work. We have one more configuration file to deal with, so close “StandaloneCommon.ini” and open up the file “CenomeCache.ini.example”.

We’re going to do the same thing as before, save the file as “CenomeCache.ini” so we don’t alter the original.

We don’t have anything to do in this file, but we did need to save it as “ini” for it to be referenced properly. Close the window, we need to do something else here.

We’re actually ready to fire up the opensim server, but there are a few more steps once we’ve got it going. One way to make this easier is to make a shortcut to the opensim.exe and modify its properties so we can scroll inside of it to see all the status messages, etc..

If you’ve done this correctly, you’ll see a shortcut appear on your desktop like this:

That isn’t too appealing, is it? Lets change the look of it and its name. Right-click on the shortcut, and select “Rename”. Lets rename this to “Opensim Server”.

Now, lets make it look like something, instead of a white dialog box. Right-click, and select “Properties”.

A window will pop up like this:

Click on the “Change Icon” button.

A warning will pop up, like this one:

Just click on the “OK” button, and another window will appear like this:

Choose an icon from what is listed in this window. (There used to be an OpenSim.ico file in other older distributions – so if you prefer to get it, download one of the older installers and extract that file to use here.) Click “Apply”.

Depending on what you chose, the result might look like this:

We’ll now alter a few things in the “Layout” tab, so we will have a scroll buffer and see what the server is doing a bit better. These aren’t absolute values, feel free to play around with them to get the right result on your system and screen resolution. Here’s what I have it set to:

Again, change these to whatever dimensions suit you best. You’ll have a chance to do that later on. Now, lets launch the server!

Double-click your opensim server shortcut on the desktop.

A dos-window will open up, and depending on the dimensions you chose, it should be big enough to see all the messages rapidly scrolling by. You may get this warning if you are running WinXP:

Just select “Unblock” so the firewall doesn’t interfere later on.

If you accidentally missed something earlier on, the program will print some red lines and error out. Close the window and go through the tutorial again and make sure you got the database connection strings right.

If all went well, you’ll see this at the very bottom of the window:

Time to name your region! You can use what you like, but for example sake, I’ll just name this “Sandbox”.

You’ll now get prompted with a Region UUID, just hit Enter to accept it.

A region location prompt will show up, hit Enter again to accept the X,Y coordinates of 1000,1000.

An Internal IP address prompt will appear, just hit Enter to accept the default of o.o.o.o.

An Internal port prompt will appear, just hit Enter to accept the default of 9000.

You’ll now be prompted with Allow alternate ports, hit Enter to accept the default of “False”.

An External host name prompt will appear, hit Enter to accept the default of “SYSTEMIP”.

A Master Avatar UUID prompt will appear, hit Enter to accept the default.

Now we’re at an important part, the Master Avatar first name. You can put what you want in here, just remember it or write it down for later. I chose to put “Builder”. Hit Enter.

For Master Avatar last name, I put “McBuilderson”. Hit Enter.

A Master Avatar (your region name) password prompt will appear. Put what you like, but make a note of it. Then hit Enter.

A whole bunch of activity will ensue, and at the end it will look something like this: (The only reason my startup time is so long, is because I was documenting all these steps for you – typically it will be much, much less.)

At this point, your simulator is up and running. But we need a viewer to connect to it! Lets get that done, shall we?

Shutdown your simulator by typing “shutdown” at the prompt, and hit Enter. (Note: your prompt will look different from mine if you chose a different name for your simulator earlier.)

The window will display some messages as the simulator shuts down, then the window will close by itself.

There are many choices for viewers, but I’m going to point you to this one – its an open alternative to the “commercial” viewer used by other grids. It also lets you connect to other grids in a flexible manner. One bonus for me is this viewer allows you to edit and scale objects in your simulator up to 256 meters. Yep, that is one big advantage when building.

You’ll see a section called “Binaries”. We’re going to click on the first link, “Download from OpenSimulator Forge”. (If that isn’t available for some reason, click on the other, but keep in mind you may see slightly different things than what I show.) Click on that link now.

Once the page loads, you’ll see some links up top. The one we’re interested in is the Windows installer, so click the following link:

Save the file where you can get to it easily.

Navigate to where you saved it, and double-click on the installer.

A window will pop up, showing a default installation directory. This should work for most people, so just click the “Install” button.

A progress bar will appear, and the installer will download some additional files to continue.

Once done, the window will change to say the “Installation finished successfully”. Click on the “Start” button to launch the viewer.

We need to change some preferences here. Select “Edit” at the top toolbar in the viewer, and select “Preferences”. A window will pop up like so:

Click on the “Grids” tab on the left.

We need to add a new grid definition for your local opensim server, so click on the “Add” button.

Hi
Firstly, Thanks for putting up these tutorials. Excellent work.
Although I have 4 regions on the live grid I need to get a SQL DB for them. So I thought I would go through these last 2 Tutorials of yours and give them a try to see if it would work with a Sandbox. Everything OK, The server comes up fine and I can see it now using SQL. But I can’t login although I have checked and double checked the Username & Password. But the viewer keeps on saying : “Login Failed. Could not Authenticate your avatar. Check your Username and Password, and check the grid if problems persist”
As I have said I have checked and its correct.
The server gives this : ”
[LOGIN BEGIN]: XMLRPC Received login request message from user ‘Joe’ ‘Bloggs’
[LOGIN]: XMLRPC Client is 0.5.1 (LL 1.22.11), start location is last
[LOGIN]: Authenticating Joe Bloggs
[LOGIN END]: XMLRPC User Joe Bloggs failed password authentication.
Not sure whats happening. (Can you help here?)
But, What I would like to know is. How difficult is this to convert to my live regions in Grid mode so they use SQL ?
Once again thank you for all your work.
Mike

Mike, can you try to create a new user to test if the password was somehow mistyped? In the server console, type the command “create user” followed by a First Name, space, Last Name, space and a password. Then use your viewer and try to connect to your sim using this new user.

I only ask, because I’ve done this personally :) Just to be sure before we go into network specifics.

Hi
Thanks for the reply.
I checked The SQL DB and noticed the user was there but it also had 2 peices of land registered. Don’t know why
I created a new user and password and it logged in first time and only one peice of land registered. So it worked first time really, Great tutorial. But I need to know how to set SQL up now for my Live regions rather than the Sandbox.
Thanks again for your work
Mike

Hello and thanks for this all tutorial you do here… i really enjoy all this info and is a pleasure for me to read! Can you please make a step by step tutorial like this one how to change from standalone to grid mode? Not to connect to another grid and just to work in grid mode… Thank you and again you doing a very good job there with this tutorials! Have a nice day and i wait a response to this.

I would love to, but currently I don’t have the hardware to do a test-bed setup to even write one. We’re talking at least five different services running on separate machines – Grid Server, User Server, Asset Server, Inventory Server and Messaging Server. The best I can do right now is point you to the documentation provided here: http://opensimulator.org/wiki/Configuration (Scroll down to the “Running OpenSim in Grid mode” section.) The docs here say you *could* do this on a single machine, but that doesn’t make any sense – as grid mode is only used to distribute the tasks among physically separate servers to reduce overall load on a single CPU. Sorry, but I’m doing all this for free, and that is the problem – I have no way of setting up this mode without buying extra machines.

Thank you for reply… i have all setup done for a long time to work in grid mode and all in one machine … all work ok but i have a problem in region coordination … when i start opensim.exe all start ok with no error, connect ok to my local grid servers but my region coordination is not what is setup from my Regions.ini ex. i have 1000,1000 and on grid is 256000,256000 … with a little calculation is 1000 x 256 = 256000 where 1000 is my region position on world map and 256 is the region sqm … i can’t understand where is the problem and how to fix to appear in right position on my world map. Maybe you can help me with some tips or something. Thanks

Hi..thankyou for the informative tutorial above..its was a great help…just wondering if you might be able to help with setting up MySql for the groups…or maybe you or someone might know of a link they might post…also..if there are any other tables and how to do it for running my own stand alone Server….
Regards Ginger :)

First time installer for middle school kids. My user has no permission to edit hair, clothes, and some other stuff. Can you tell me what I did wrong or how to fix it? I am using standalone and SQLLite db. I follwed everything else you did..I think! Can’t find the answer anywhere!
Please???????

I believe you need to create a new item, whether it is clothes, shape, hair – then you’ll be able to edit it. I don’t really do much with personal appearance since I just build, but that should get you going. You may also want to consider using SQL versus SQL-Lite for performance reasons.

Thanks again for all your help! I have MYSQL working with an opensim database. Now I can’t configure Opensim.ini. I have the newest version and I don’t see the Standalone section in the ini file. What do i do now?

I haven’t checked the latest version, but when I wrote the updated guide you had to go to the opensim\bin\config-include directory to find the file “StandaloneCommon.ini.example” which you use as a template. If that has changed then the developers have pulled the rug out from under us again, unfortunately.

About

Opensimulator is the future of the ‘3D Web’. Open code, open protocols. Sure, there are closed-off implementations that promise a few bells and whistles, but once you’ve experienced the power of running your own simulator, you won’t want to return to the walled garden again.

I build primarily, and I enjoy the fact that I can export my content to a safe backup that I control. Using a simple command at the console, “save oar <filename>.oar” my whole region is backed up, safe and sound. When I first started, I wanted this feature immediately. Now, with opensim I can build my heart out and know that off-site backup is possible and not locked away in server farm out of my reach.

You can link regions into your own creative collective, have a private grid at home or a standalone to let your kids learn on without any interference. It is the power of collaborative 3D spaces where it belongs, in the hands of everyone.