Virtual Worlds

Changing OpenSim’s User Database to MSSQL

Stacy Vicknair — Thu, 02 Oct 2008 04:58:15 GMT

Here we are at the second week's task for the Manhattan Project: switching the user's database to MSSQL instead of SQLite. I'll be honest, there weren't any valuable resources I found for assistance in the creation of this tutorial. Mostly it was a combination of Try / Fail and guessing based on what I saw in the code for the MSSQL dll in the project.

I might say that there weren't resources, but what I mostly mean is no tutorial. There are some .sql files to help get the database started, but that's the extent currently.

Now, things you need to know before I begin:

If you want to get a better idea of what's going on, what OpenSim is and what it can do for you, check it out at http://www.opensimulator.org.
The OpenSim tutorials represent a face-value documentation of what worked for me. I would assume that if you follow these instructions they will lead you to success, but I have to apologize ahead of time that I will not be the most valuable resource if for some reason this doesn't work for you. The source changes frequently, and I hate to think how soon I’ll be outdated.
Be proactive. I'll start each section with a bolded header. If you think you can manage what you need to do just by reading the header, then go for it. Frankly, if you think you can do this without my tutorial, go for it too. I'm adding this tutorial for the sake of helping those who may straggle behind with the project.

With that out of the way, these are what you should have / will need prior to this tutorial:

An operational OpenSim server, and access to the source.
An operational SQL Server. This tutorial is designed for someone who is using SQL Server 2005, but should have acceptable parallels to previous or future versions.

And finally before we get started, I am dreadfully making some assumptions, listed now:

OpenSim server is on the same machine as the MSSQL server.
SQL Server is operating in mixed mode authentication. OpenSim's MSSQL dll doesn't natively support windows authentication, but it is something that could be added. There may be security reasons that this isn't supported, but currently I am clueless to what they'd be.

Let's Get Started!

1. Create a new SQL Server Database, called OpenSim.

Frankly, the database doesn't have to be new, and it doesn't have to be called OpenSim, but for the sake of segregating the tables for OpenSim, and for keeping things logical, this is what I did.

Open SQL Server Management Studio Express and connect with the authentication you've set up. On the left sidebar you'll see a list of all the different stuff on your SQL Server. Right click where it says Databases and select New Database...

In the resultant New Database window, put OpenSim as the database name and specify an owner, then click Okay.

2. With your new database selected, load and run the various .sql files.

Special thanks to Chris Hart for unearthing these .sql files!

Go ahead. Try and find the .sql files that you need to run to initialize the databases. I'll wait.

Now before you hang yourself from the nearest ceiling fan, here's where they are:

\OpenSim\Data\MSSQL\Resources

After returning the rope to the garage and the chair to the kitchen, open all of the .sql files in SQL Server Management Studio Express. Towards the top of the program, you'll see a toolbar option with a red exclamation that says Execute. Just to the left of that, make sure that the drop-down list has OpenSim (or whatever you might've named your database) selected. Then for each of the .sql files, hit Execute.

Note: I'm certain not all of these are necessary for migrating just the users database, but I do'em all anyways. Also, one of these files consistently fails, but don't worry, if it's the same one that fails for me it isn't necessary for the user's migration. Hopefully there will be a fix within the community if the plan ever becomes to migrate all databases.

3. Add a new login to your database with db_owner permissions to the newly created database.

Again, thanks to Chris Hart I have learn something new for another day... here's what she has to say for creating a new user (this is specific to SQL Server 2005)

To create a user account for running your OpenSim on SQL Server, you need to firstly enable Mixed Mode authentication on SQL Server. Right-click on your database server in Management Studio and select Properties, then go to the Security tab and select SQL Server and Windows Authentication mode, click OK.

Back in Management Studio, expand the Security node and in the Logins section right-click and create a new user, called whatever you like, select SQL Server authentication, give it a strong password and select the OpenSim database as the default database. Click OK.

Then navigate to the OpenSim database and go to the Security, then Users section. In there, create a new user, select your new admin account and make sure it has the db_owner role in the Database role membership section. Click OK and try using that account to log in. Makes it a bit more safe than using an account that has control over the entire database server.

Thanks again Chris :)

4. Change the userDatabase_plugin value in the OpenSim.ini to "OpenSim.Data.MSSQL.dll"

Browse to the bin folder of your built OpenSim and locate the OpenSim.ini file that you created in the previous tutorial. Open it up, and search for userDatabase_plugin.

You'll see that one of these isn't commented, and some other options are commented out. Oh so conveniently, the MSSQL option doesn't exist. hoorah. Make a copy of the active line, paste it, then comment one out. Then, on the uncommented line, replace the assigned value with "OpenSim.Data.MSSQL.dll".

You'll end up with something like this:

;userDatabase_plugin = "OpenSim.Data.SQLite.dll"

userDatabase_plugin = "OpenSim.Data.MSSQL.dll"

Save the OpenSim.ini and close it.

5. Copy mssql_connection.ini.example to mssql_connection.ini and update it with your database's information.

Remember when I said this is a face value documentation of what worked for me? Well, it's about to shine through.

After copying the mssql_connection.ini.example to mssql_connection.ini, fill in the information like it were a connection string in ini format. Follow the guidelines provided in the example.

For datasource, if your OpenSim will run on the same computer as the SQL Server, set this to localhost\.

If you are unsure of your SQL Server's instance name, open up SQL Server Management Studio Express and look at the Server Name in the Connect to Server dialog box. This is in the format:

(Computer Name)\(Server Name)

For initial_catalog, set it to the name you gave your new database (for example, OpenSim)

Finally, for user_id and password, use what you created in the earlier steps.

Save out the mssql_connection.ini file and then try running your server.

6. Run your OpenSim.exe, and hope it doesn't crash.

I know the process worked for me, but lord if I know how the whole thing will go down for you. Basically, there are a couple key ways to recognize that your connection was successful:

OpenSim.exe kept running until you got to the Region#: prompt. This means success. The opposite of success is when OpenSim crashes and you see a lot of red text. Sadly, I don't know how helpful I will be if this happens to you.

The master user gets migrated to your SQL Server's Users table. Open up SSMSE (SQL Server Management Studio Express) and browse to Databases > OpenSim > Tables. Right click the users table and select Open Table. You should see some new entries that were generated after OpenSim.exe was run.

Finally, if you recognized these couple successes, whip out your Second Life client (with the modified path to connect to your region) and log in. At this point, I really wish for your success!

Technorati Tags: second life,opensim tutorial,opensim,MSSQL,sql server 2005,Chris Hart

Installing and Running OpenSimulator

Stacy Vicknair — Thu, 02 Oct 2008 04:36:56 GMT

Now that the Manhattan Project has taken its first few baby steps, I think it would be best if I made a series of tutorials for those who want to keep up with the happenings, but might have lagged behind. This is the first in a large series of tutorials that I (and all those involved) want to have available to help those who have a little trouble getting started.

To get some things straight, at least for myself, OpenSim is not a client for Second Life (I swear, this is what I thought before I got into it). OpenSim is a open source server-side application for running grids and single regions, and you will be able to connect to your region / grid via the Second Life client. So basically, you'll be able to host your own capable sandbox.

Now, with that said, I do want to give a couple words on how I feel you should use these tutorials:

Learn from my mistakes. I'm nowhere near a genius, nor do I claim to have superior knowledge on the subjects I'm going to walk you through. I'm giving you a face value representation of what worked for me.
If you think you can get through some of these steps on your own, then do it! Honestly, I want this tutorial to be as straightforward as possible, but I also want you to explore your own ability. You'll get a lot more satisfaction if you take the time to do what you think you're capable of without the full description. AS A RESULT: I'm going to bold the main goal of each section in Bold. I'll go more in depth in regular font.
Don't expect my tutorials to get you through things on the same timeline as the project. I'm going to stagger them past the week that they were expected.

Okay, with all that out of the way, let's get you started (and hopefully finished too!)

As much as I hate to do this, I'm going to make the following assumptions:

Have a version of C# installed. If you don't have this, follow this link and follow the tutorial, except install C# Express instead of VB Express.
Have TortoiseSVN installed. If you don't have this piece of software, you can download it here.

And one final reminder: If you get stuck or for some reason your OpenSim starts having errors, just delete the folder and start over. I promise, I did have to do it at least once.

Okay, lets get started.

1. Set up a folder to download the source using TortoiseSVN.

I just created a new directory on my C drive called OpenSim. Next, Right-Click that new folder, and if you have TortoiseSVN installed you should see the option SVNCheckout....

In the window that appears, set the URL of Repository to http://opensimulator.org/svn/opensim/trunk and click Ok.

This'll start a long download process, that will hopefully yield a success screen. Hit Ok.

2. Generate a Solution File, then compile OpenSim.

Try not to overcomplicate this for yourself. It really is this easy.

First, you will have to run a batch file to generate a solution file so that you can open the project in C# (Express or whichever). From what I read, it said it is necessary to run this as Admin in Vista, but I didn't have to. In fact, it didn't seem to work if I tried to run it in Admin. Maybe I'm a noob.

If you are compiling for C# 2005, run the runprebuild.bat batch file. If for 2008 (which is what I did) use the runprebuild2008.bat which you will find in the base directory that you downloaded the source into. It will open a command line and run for a short bit. The result is an OpenSim.sln file in the base directory you downloaded the source into.

Open the OpenSim.sln file. It will take a small amount of time to load all of the files, and then all you have to do (believe me, at this point I was scared of what I'd have to do to get this to compile...) is select Build -> Build Solution. Give it some time, then it should say 63 Succeeded in the output window in Visual Studio. Go ahead and close Visual Studio, if you're like me, you want to do it sooner than later to avoid breaking the code somehow magically.

3. Configure OpenSim.

There are only a few steps necessary to get OpenSim running. But honestly, having OpenSim running does not give you much until you actually connect.

Firstly, browse to the bin directory inside the base directory where you downloaded the source. Find and make a copy of OpenSim.ini.example and name it OpenSim.ini. Open OpenSim.ini and add ; to the beginning of the line:

storage_plugin = "OpenSim.Data.Null.dll"

remove the leading ; from the following line:

;storage_plugin = "OpenSim.Data.SQLite.dll"

Editing those previous lines allows your built prims to be saved to a SQLite database instead of vanishing every time the server restarts.

Finally, just after the first line of the file, add the following line:

physics = OpenDynamicsEngine

Skip the mistake I made: If you don't add this line to the OpenSim.ini, everything will still run fine. The issue is that when you start to build prims and try to walk on them you will not be able to. The physics engine has to be in place for you to be able to walk on prims.

That's all for configuring the ini file!

4. Run OpenSim!

Skip the mistake I made: It might be fairly obvious to you, and almost expected if you do a lot of Unix / Linux installs, however I didn't realize at first that the OpenSim was asking me more questions when I ran it for the first time. I was trying to enter in different commands and whatnot, and this fatal error led to my first restart :(

Note for Vista Users: You will need to run this in admin mode. I found it easiest to make a shortcut on my desktop to the exe that had Run as Administrator specified.

In the bin directory, run the OpenSim.exe. After a little loading, it'll ask you some initial questions. I recommend hitting enter to use the default answer on all of these except:

Region Name - Give it some unique flare, this is the name of your area!
External Host Name - If you are going through a router or firewall, make sure port 9000 is forwarded to your machine that the server is on. Also, set this value to the external IP for your network. (If you are not sure, try http://www.whatsmyip.com to find it out)
First, Last, and Password for Master User - Set these to what you want to log in as.

After these are through, you are ready to configure a shortcut to connect your Second Life client to your new region!

5. Connect to your server!

Copy your shortcut to Second Life, then right-click it and select Properties. Add the following lines to Shortcut Target:

-loginuri http://127.0.0.1:9000/ -loginpage http://127.0.0.1:9000/?method=login

Using the information you provided for the master user, log in!

Warning: This is a warning from the OpenSim's connecting page, thanks FDG!

One source of problem - like uploaded pictures not showing or not being able to move directly after logging in into a public grid - is having the "Maximum Bandwidth" setting in the Preferences of the SecondLife viewer on the "Network" tab set too high. So set it to about 250 kbps, when you encounter such issues.

http://opensimulator.org/wiki/Connecting

6. Final Notes

Okay, so you got it running, but just remember this: type quit and hit enter in the server command line when closing down. This will prevent errors with your sim!

And Finally, here are the resources used to help me get my sim up, as well as credit where credit is due.

http://opensimulator.org/wiki/OpenSim_Build_Instructions
Special thanks to G2 Squared for the quick run-through that served as a backbone to this tutorial!

Technorati Tags: virtual worlds,opensim tutorial,second life,opensim