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

Navigate back to opensim\bin, and right-click on opensim.exe – choose “Send To” –> “Desktop (create shortcut)”.

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.

Open your favorite web browser, and navigate to this page:


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.

In the Login URI box, put this in: http://localhost:9000/

Platform should be set to “OpenSim”.

Grid Nickname can be whatever you’d like, but for this example, I put in: poschgrid

Grid Name can be whatever you’d like, but for this example, I put in: Tim Posch’s Grid

In the Login Page box, put this in: http://localhost:9000/?method=login

Helper URI, Web Site, Support URL, Account URL and Password URL can be left blank.

Rendering Compatibility is checked by default, you can leave it this way.

After you are done, click “Apply”. Now your grid definition should be available from the “Select a grid” dropdown up top. After you select it, it should look something like this:

Click the “Default” button to make this grid the one you will use when starting up the viewer, for convenience. Hit “Apply” and then “OK”. You can now exit this window. Shut down the viewer for now.

We need to restart the opensim server, so double-click on the icon you have on your desktop.

The server window will open, you’ll see a bunch of status lines, then finally the “Region (Your Region Name) #” prompt.

Now we are ready to connect! Fire up the viewer, and make sure the default grid is the one you defined earlier. If not, go to preferences and set it properly.

Once you have it set, you will see a white page that has First Name, Last Name, Password. We don’t need to use this, but it lets us know that the opensim server is up and running.

At the bottom, enter your First/Last/Password that you set when configuring the server earlier. For me, that would be Builder, McBuilderson, (PASSWORD).

Click the “Login” button. You should see a progress bar and connect to your region!

If all went well, you’ll be floating above a bump-like island in the middle of your very own simulator.

Good job!

I’ll cover some customizing commands in my next tutorial… stay tuned!


About this entry