12. Using Grid Info

Opensim contains a powerful feature, called Grid Info, that allows you to provide your users with useful information and added functionality. However, only viewers that support Grid Info can fully utilize all of its features, such as the Hippo Viewer. The SL Viewer can only use one of the Grid Info features, and that will be described.

Basically, Grid Info returns information to the viewer, once it has issued a get_grid_info call, that auto-configures the viewer for you. All you need to do, in the Hippo Viewer, is to provide the hostname and port number of your server, press the Get Grid Info button, and all the other fields will be auto-populated for you. See these BEFORE and AFTER screenshots.

Click on Apply to permanently store the data, then on OK.

The first thing you will notice is that the splash screen changes, and now shows the nifty drop-down box containing the names of all the regions in your grid. The user can then select which region they wish to arrive in, then login. In fact, the splash screen changes depending on the time of day in the region, be it Sunrise, Midday, Sunset, or Midnight.


Step 1: Setting up Grid Info
To set things up, go into opensim.ini, and near the end you find the Grid Info section.

The options are as follows (and the values I have given below are the ones that produced the AFTER screenshot above):

; login uri: for grid this is the user server URI
login = http://anubia.servegame.org:8002/

; long grid name: the long name of your grid
gridname = "Anubia"

; short grid name: the short name of your grid
gridnick = "anubia"


; login page: optional: if it exists it will be used to tell the client to use
; this as splash page
welcome = http://anubia.servegame.org/loginscreen.php

; helper uri: optional: if it exists if will be used to tell the client to use
; this for all economy related things
economy = http://anubia.servegame.org

; web page of grid: optional: page providing further information about your grid
about = http://anubia.servegame.org/about

; account creation: optional: page providing further information about obtaining
; a user account on your grid
register = http://anubia.servegame.org/register

; help: optional: page providing further assistance for users of your grid
help = http://anubia.servegame.org/help

; password help: optional: page providing password assistance for users of your grid

password = http://anubia.servegame.org/password


Tip: If the Grid Info does not match what you have entered into your opensim.ini, try clearing the cache, or stopping and restarting the UGAIM service and opensim.exe.


Step 2: Setting up the Web Interface for Grid Info
Of course, the four pages referred to above, that provide information about your grid
, how to register, provide help, and what to do if a user has forgotten their password, have to be written by you, and placed in the Web Interface wamp\www folder.

You may also wish to use your own images for the splash screen. To do this, you will need four images, 1280x939 pixels, in jpg format, named login1.jpg, login2.jpg, login3.jpg and login4.jpg, and put them into the following folder (replacing the default images): wamp\www\images\login_screens\


Step 3: Seting up the Viewer

To enable your users to use Grid Info:

Hippo Viewer
Start the Hippo Viewer, then click on the Grids button, and add this in the Login URI box:

http://anubia.servegame.org:8002

Click on the Get Grid Info button, and all the fields will be populated for you.


SL Viewer
Unfortunately the SL viewer does not currently support Grid Info, but you can provide your users with that nice login screen, with the drop-down Region List. To do this:

Right-click the shortcut icon, Properties, Shortcut Tab,

add this switch to the end of the Target,

-http://anubia.servegame.org/loginscreen.php


Step 4: Changing the Arrival Location within a Region
By using the loginscreen feature of the Web Interface, you will have a drop-down list of all the regions in your grid, and you can decide which region to arrive at by selecting that region from the drop-down list.

However, the location within that region that you will arrive at is set to a default of 128,128,50

Now, that just might be a tad inconvenient. On one of my regions that location was inside a mountain, and on another I appeared within a wall of a palace!

So, how do you get around this?

Step 4a: Set a Landing Point
In each region, go to the place where you would like yourself and others to arrive at, and from your viewer go to About Land (by clicking on the Region name at the top of your viewer screen in the middle of the menu bar), click on the Options tab, set the Teleport Routing to Landing Point, then press the Set button. Do the same for each region.

Step 4b: Turn off the Default Location
Navigate to your Web Interface loginscreen folder, and open the region_box.php file. Look for the line that contains this at the end:

$regionName?">/128/128/50'">

and delete the (/128,128,50) changing it to:

$regionName?">'">

(Note: it finishes with close chevron, single quote, double quote, close chevron)

Save

(no need to restart anything, it will be available the next time you open your loginscreen-enabled viewer)


11. Using Money in OpenSim

Before embarking on this tutorial I would urge you to read my blog entry, 'Money, that's, what I want', in the Chapter & Metaverse blog for the 29th November.

==================================================

This tutorial assumes that the previous tutorials on Installing Opensim, Migrating to MySQL, Working in Grid Mode, and Creating a Web Interface, have all been completed.

The previous tutorial on Creating a Web Interface detailed how to install and configure WAMP and the OpenSimWI (redux). These applications already contain all you need to implement currency in OpenSim, they just need configuring and enabling.

Before starting this tutorial, if you are using DynDNS, make sure that it is working correctly, and resolving to your true IP address, and not using any form of redirect.


Step 1: Configure php.ini
Navigate to wamp\bin\apache\apache2.2.8\bin\php.ini and open the file. Near the top of the file are the Language Options, ensure that the following are set:

short_open_tag = On

asp_tags = On

Near the middle of the file is the section Dynamic Extensions, under Windows Extensions uncomment the following:

extension=php_curl.dll

extension=php_xmlrpc.dll

( the extension=php_mysql.dll should have been set in the previous tutorial)

Save.

(php will need to be restarted for these changes to take effect [not applicable to Linux users], but we will do that later).

(Linux users should refer to this link to install php curl).


Step 2: Create a Banker Avatar
Using the Web Interface (but not using the opensim console or the user console), create a new user, call him Banker Avatar (the name can be anything you like, but it must be a name that you can immediately associate with currency in opensim).

Using Toad, phpMyAdmin, or the mysql console, look up this new user, and copy his UUID. Alternatively, you can go into the Web Interface admin, Manage Users, click on Edit beside the Banker Avatar, and his UUID will be shown in the user details. You will need the banker's UUID in the following steps. I will now assume a UUID for Banker Avatar of:

d91452bf-c474-4bbe-a91f-f4629c5bac4f


Step 3: Configure config.php
Navigate to wamp\www\settings\config.php and open the file. Go to the Money Settings section and insert the Banker's UUID:

$economy_sink_account="d91452bf-c474-4bbe-a91f-f4629c5bac4f";

$economy_source_account="d91452bf-c474-4bbe-a91f-f4629c5bac4f";

Save.


Step 4: Configure opensim.ini
Go to the [Economy] section and set the hostname and path to the currency.php and landtool.php files, and set the Banker UUID to the Base Account, for example:

CurrencyServer = "http://anubia.servegame.org/currency.php"

Landserver = "http://anubia.servegame.org/landtool.php"

EconomyBaseAccount = d91452bf-c474-4bbe-a91f-f4629c5bac4f


In the [GridInfo] section of opensim.ini there is a helper uri setting. Set as follows:

economy = http://anubia.servegame.org/

Save.

Step 5: Set the Currency Conversion Value
The currency conversion is set at a default value of 1 cent = 1 currency unit. This can be changed by using Toad, phpMyAdmin, or the mysql console, to open the wi_economy_money table, and changing the CentsPerMoneyUnit value to whatever you like.


Step 6: Modify the Viewer Target Parameters

The following example values are for my anubia grid, which has the hostname,

http://anubia.servegame.org

This should be replaced with your grid's own hostname or IP address.

SL Viewer
Right-click the viewer shortcut icon, Properties, and under the Shortcut tab you will have a Target similar to this:

"C:\Program Files\SecondLife\SecondLife.exe" -set SystemLanguage en-us -multiple -loginuri http://anubia.servegame.org:8002

Modify this to the following:

"C:\Program Files\SecondLife\SecondLife.exe" -set SystemLanguage en-us -multiple -loginuri http://anubia.servegame.org:8002 -loginpage http://anubia.servegame.org/loginscreen.php -helperuri http://anubia.servegame.org/


Hippo Viewer
Set the following parameters for your grid:

Login URI: http://anubia.servegame.org:8002

Platform: Opensim

Grid Nickname: anubia

Grid Name: anubia

Login Page: http://anubia.servegame.org/loginscreen.php

Helper URI: http://anubia.servegame.org/

Web Site: http://anubia.servegame.org/about


* For both viewers the trailing slash for the helper uri is important.


Step 7: Restart WAMP and the Services

To put all these changes into effect you must close down OpenSim and stop all the Wamp services, and the Wamp server. Restart the wamp server, restart all the services, and restart Opensim, and money should now be enabled.


Step 8: Update the Database

As only users that are created via the Web Interface can log in there and look at their transaction history you might want to consider 'converting' the existing users created via the console. To do this simply log into Web Interface Admin, and above the left-hand Menu you will see an option to Update Database. Clicking on this will synchronise the user table with the wi_user table, and make them all Active.


Known Bugs and Limitations
The currency modules in OpenSim are not without their bugs, but do not expect them to be fixed anytime soon, they are a low priority right now for many of the OpenSim development team, and a zero priority for some.

Users who have got money working in their grids report that
money transfers and buying land both seem to work fine, but further report issues and limitations such as:

  • Money goes missing for no apparent reason (often when crossing region borders). Relogging usually restores the correct balance.
  • A random 'Transactions may not be available' error message.
  • Buying from an object crashes the client.
  • Uploads do not take any money.

Troubleshooting
Some people have reported that their installation did not work and eventually they found that either the wrong php.ini had been edited (as there is another in the php folder) or that xmlrpc was not running.

A handy check is to create the following php script in notepad (replacing the square brackets with chevrons):

[?php
phpinfo()
?]



Save this as testphp.php and place it in the wamp\www folder.

To use it just go into your browser and type your hostname, then the script name, for example:

http://anubia.servegame.org/testphp.php

This will tell you lots of information, including if php has been set up correctly, if curl and xmlrpc are running or not, and lots more besides.


Finally
Treat the whole issue of money in opensim with extreme caution, and at your own risk. The developers have repeatedly said that the current stage of opensim development does not support inworld currency, and the available modules should be used for testing and development only, and are not supported.




10. Creating a Web Interface - Part 3/3

The last part of this tutorial will deal with setting up a mail server. Basically, when someone registers on your Web Interface, an email will be automatically sent to them, which they must open and click on the Confirmation link, before the account becomes active and they can log in.

Note: Another authentication system, using Captcha, is described at the end, in case you cannot use email due to Port 25 being blocked.


Step 1: Download the Email Server
The preferred email server is the Postcast Server Free Edition, which can be download from here.

Unzip the zip package, and double-click Setup.exe. The standard installation wizard will then launch. During installation I got an error, that said that gcpbbln.ocx failed to register. I chose Ignore, and have suffered no ill effects.


Step 2: Configure the Email Server
The installation process should have placed an icon on the desktop, click this to start the server. The Postcast Server Setup Wizard should then start. The settings should be as follows:

Incoming Connections:
Check the Allow access ONLY for users with these IP addresses, and select 127.0.0.1

Mail Sending Frequency:
Select Immediately

Run-time settings:
Select all three options

Emailclient settings:
Nothing to change.


Step 3: Start the Email Server
You must remember to have the email server running for it to be used! Double-click the icon it has placed on the desktop, then you can minimise it to the System Tray.



Troubleshooting
Test the facility by creating an account, and using a known good email address. The email should pop up in the Email Server window when the account is created, so look out for it.

If the email shows up in the server, but does not appear to get sent, then check that the email is valid, and has been typed in correctly. Try another email address.

It has been noted that an email address can only be used once to create a user. If you try to create another user, and provide an email address that has been used before, then you will get a "This email address is already in use" message, and you must supply another email address to continue.

It should also be remembered that many ISP's now, especially on home connections, block outbound port 25 to prevent compromised machines spamming and instead force you to relay through their SMTP servers.


Captcha
The main purpose of email confimation is prevent web-bots from creating accounts on your grid. Another method of prevention is the use of the Captcha system.

To use Captcha instead of email confirmation just download this zip file. Instructions for use are included inside (it is very, very simple).

09. Creating a Web Interface - Part 2/3

Step 1: Download the WI Software
The Web Interface software can be downloaded from the Forge. Click on the Files tab, and the zip file is available there. Download it, and unzip the contents (8 folders and 12 files). Select all these folders and files, right-click and choose Cut. Navigate to wamp\www, there should be just one file there, index.php, delete it, then paste the WI folders and files there.

Step 2: Import the WI Tables
Open phpMyAdmin, and select the opensim database from the left pane.
On the right, above the database structure, select the Import Tab.
Navigate to the wamp\www\sql_update folder, there should be 12 sql file here
Import each of these 12 files in turn, ignoring any error messages about empty results.
Close phpMyAdmin

If you now go to your domain in a browser, you should see the WI, but with some junk code at the top of screen. Don't worry about that, it will be fixed.

Step 3: Restart Apache
Click on the Wamp system tray icon, and select Apache, Service, and Restart Service.

Step 4: Configure the Web Interface
Navigate to wamp\www\settings and open the config.php file in Notepad. At the top should be the System settings:

SysName: this is the name that will appear in the Title Bar of your WI.
SysURL: this is the address of your host (mine was http://anubia.servegame.org)
SysMail: provide a valid email address for yourself here

Now scroll down to the Database section, and enter your database details like this:

define("C_DB_TYPE","mysql");
//Your Hostname here:
define("C_DB_HOST","localhost");
//Your Databasename here:
define("C_DB_NAME","opensim");
//Your Username from Database here:
define("C_DB_USER","root");
//Your Database Password here:
define("C_DB_PASS","mypassword");

Now save this file

If you now go back to your browser, enter the url of your host again, and refresh the page, you should see it OK

Step 5: Change your WI Admin Password
In your browser, enter the url of your host again, but add /admin/ at the end, like this:

http://anubia.servegame.org/admin/

The default user name is admin, and the password is test. Enter these and inside select Change Admin Pass from the menu in the left pane. In here you can change your password, and Save.


In the last part of this tutorial we will set up the mail server, for registration confirmation.

08. Creating a Web Interface - Part 1/3

What is a Web Interface (WI)?

Take a look at mine and see for yourself.

To create a WI you will need three pieces of software, and this is the reason for me splitting this tutorial into three sections.

IMPORTANT:
Many ISP's now, especially on home connections, block outbound port 25 to prevent compromised machines spamming, and instead force you to relay through their SMTP servers. This means that WI will not work, as the email confirmation will not get through (as it needs Port 25).

To test if your ISP blocks port Port 25, download the free utility Putty. Open Putty, and put the following:

Hostname: gmail-smtp-in.l.google.com
Port: 25
Connection Type: Telnet

Click Open

A DOS-like window should open, and you should get a response similar to this:

220 mx.google.com ESMTP b17si7069788fka.27

If you do you are good to go and can proceed with this tutorial. If you don't get a response then you cannot use email for new user confirmation or for group messages, however, you can use Captcha instead for new user confirmation, and this is described in Part 3.

Now hit the Enter key in that DOS-like window, and type QUIT (in capitals). That will close the window and Putty.

Software Required
The first piece of software you need is WAMP. WAMP stands for Apache, MySQL, PHP on Windows (sort of back-to-front I know). This free suite is amazing.

Basically the suite installs:

Apache: this will turn your server into a fully-fledged web-server

PHP: this will enable your server to run php scripts to run things such as a Web-Interface

MySQL: the preferred database engine for opensim

The suite has some great tools included too, such as phpMyAdmin which allows you to explore and change your MySQL database.

Before we start, if you already have MySQL installed on your machine, you should make a backup of your database, and uninstall MySQL. To do this:

a) Create a Backup of your database
Open a command console window (go to Start, Run, and type 'cmd' (without the quotes) in the Open: box.). In the command console type the following:

mysqldump -u root -p opensim > c:\opensim.sql

This command starts the mysqldump backup utility. The full syntax for this command is:

mysqldump -u [username] -p [databasename] > [backupfile.sql]

where:

username = the user name you use in MySQL, usually 'root' the -p switch will prompt you for the password you use for MySQL

databasename = the name of the database you wish to backup, in our case this is 'opensim'

backupfile.sql = the path and name of the backup file, can be anything, for example, c:\opensim.sql'

b) Uninstall MySQL
If MySQL is running as a Windows service you must first stop it. To do this go to Start, Settings, Control Panel, Administrative Tools, Services. Scroll down till you see MySQL, select it, and choose Stop the Service from the left-pane.

It is much easier to use the same User name and Password for your new MySQL so make a note of it now, before uninstalling.

You can now uninstall MySQL in the normal way, by going to Start, Settings, Control Panel, Add or Remove Programs. Scroll down until you see MySQL Server 5.0, select it, and choose Remove.

Step 1: Installing WAMP
You can download your copy of WampServer from here. I do not intend to reinvent the wheel, as there is an excellent step-by-steo guide to installing WampServer, with screenshots, on the JLBN website. Just follow their steps, to the bottom of the page, then it will ask, When you are ready, click here to go to the next page, and so on to the end.

Once WampServer is installed you will see the icon in the System Tray, left-click it, and at the bottom of the Wamp menu you will see Put Online, choose this, then select Start All Services. Wamp and its services are now running.

Step 2: Configure MySQL
From the Wamp menu select phpMyAdmin.
In the left pane select mysql.
Check the checkbox besides 'user' and then click the Browse icon to its right.
The first entry should be 'localhost' 'root', check the checkbox then click the Pencil edit.
The first three Fields are Host, User and Password.
For Host, make the Value localhost. Leave the Function blank.
For User, make the Value root (or whatever MySQL username you chose). Leave the Function blank.
For Password, make the Value the MySQL password you chose. For Function, select PASSWORD from the drop-down box. This is very IMPORTANT.
At the bottom of this table you will see a Go button, hit it.
In the left pane, at the top, you will see a little Home icon, click this.
In the right pane you will see the option to Reload Privileges, hit this, it should say Reloaded Successfully.
Now click on Databases, and in the Create new database box, type 'opensim' (without the quotes) or whatever name you have used for your MySQL opensim database.

If you get an 'Access denied' error at this point, do the following:

Open Explorer and navigate to wamp\apps\phpmyadmin
Open the config.inc.php file in Notepad
Find the line: $cfg['Servers'][$i]['password'] =
The password in the quotes will be blank, enter your MySQL password here, save.
Close down phpMyAdmin, then reopen it (to clear the cache)
Click on the Home icon, and you should be able to create a database now

Use the same name for your database that you used previously (if you were using MySQl previously).
Once the database has been created it will appear in the left pane.
Close phpMyAdmin

Step 3: Configure Apache
Click on the Wamp system tray icon, go to Apache, Service, and Stop the service.
Using Explorer navigate to wamp\bin\apache\apache2.2.8\bin
Open the file php.ini and scroll down to Language Options
Find the line that says: short_open_tag = Off and change this to On
A couple of lines below should be: asp_tags = Off, change this to On too
Now scroll down till you find the [Mail Function] section
Under Win 32 there should be a line that says
;sendmail_from = me@example.com
Remove the leading semicolon
Save and close.

Apache also needs the TCP port 80 opening in your firewall, so do this now.

Now click on the Wamp system tray icon, go to Apache, Service, and Start the service.


Step 4: Import your MySQL database
We are now ready to import the previously backed-up opensim database (c:\opensim.sql)

Navigate to c:\opensim.sql (or wherever you saved it to, right-click and choose Cut
Navigate to: wamp\bin\mysql\mysql5.0.51b\bin and paste the file there
Open a cmd window, and change directory (cd) until you get to the bin folder above
Now type the command: mysql -uroot -p opensim < opensim.sql

You will know when the database has finished loading when you see the dos prompt again.


Step 5: Check that all is OK

You might want to check at this point that you can see your Wamp server page. Go to your domain (or IP address) in a web browser, with no port number, (for example, mine was http://anubia.servegame.org), and you should see the Wamp server page.

If this is OK you can now start the next part of this tutorial and install the Web-Interface software.

07. Using Hypergrid

What is Hypergrid?
Hypergrid is now included in the standard build of OpenSim, since release r7471, and allows for teleporting between any two opensims, whether they are in standalone or gridmode. This should not be underestimated. Hypergrid could be said to be the glue that binds all OpenSims together into one vast Metaverse. From now on, you can teleport directly from with within your viewer, using the Map, to any other OpenSim, including all sims in the OSGrid and 3rd Rock, for example, or to your friend's standalone, providing, of course, that they permit you, by giving you the URL of their sim.

Enabling and Using Hypergrid

Step 1: Enable Hypergrid
To enable Hypergrid you need to change just one line in the opensim.ini file. Look for the WorldMapModule parameter in the [StartUp] section, and comment it out (by preceding it with a semicolon), and replace it with:

WorldMapModule = "HGWorldMap"

Step 2: Set a Home Position
In order to use Hypergrid you must first set a home position in one of your own regions, if you have not already done so.

Step 3: Ensure your Network Parameters are setup Correctly
To use Hypergrid your network settings must use the external hostname or IP address, and not the local loopback of 127.0.0.1. So, for example (assuming that your hostname is http://myhost.servegame.org):

Standalone Mode

[Network]
http_listener_port = 9000
remoting_listener_port = 8895

grid_server_url = http://myhost.servegame.org:9000
grid_send_key = 1234
grid_recv_key = 1234

user_server_url = http://myhost.servegame.org:9000
user_send_key = 1234
user_recv_key = 1234

asset_server_url = http://myhost.servegame.org:9000

inventory_server_url = http://myhost.servegame.org:9000


and for Gridmode

[Network]
http_listener_port = 9000
remoting_listener_port = 8895

grid_server_url = http://myhost.servegame.org:8001
grid_send_key = 1234
grid_recv_key = 1234

user_server_url = http://myhost.servegame.org:8002
user_send_key = 1234
user_recv_key = 1234

asset_server_url = http://myhost.servegame.org:8003

inventory_server_url = http://myhost.servegame.org:8004

Also check your 5 UGAIM xml config files:

UserServer_Config.xml
GridServer_Config.xml
AssetServer_Config.xml
InventoryServer_Config.xml
MessagingServer_Config.xml

and change all references to 127.0.0.1 to myhost.servegame.org


Step 4: Create a Shortcut
Create a shortcut to opensim.exe on the desktop, right-click it and choose properties, and on the Shortcut Tab go into the Target box, and at the end add a space and then -hypergrid=true

so it looks something like this:

"C:\Opensim\bin\opensim.exe" -hypergrid=true

Step 5: Create a Link Region
To set up a link region (the place you wish to teleport to) you need two things:

a) A place on your own gridmap that is unused, preferably not adjacent to any of your existing regions, but close by. So, for example, in my grid I have 25 regions in a 5x5 grid layout. The X-Y coordinates for each region range from 999-1003 in the X-Axis and the same for the Y-Axis. So I chose 999 1005 for my first link-region.

b) The URL for the region you wish to teleport to. For testing purposes you can use a location in the OSGrid, osl2.nac.uci.edu, with a port number of 9006.

You can now create the link region by typing the following command in the opensim.exe console (after you have started it):

link-region 999 1005 osl2.nac.uci.edu 9006 OSGrid Gateway

(Note: the above address is OSL2, not OS12. Also, the 'OSGrid Gateway' is just the name I have given on my Map for this region, you can choose anything you like for this name, it is not the name that the region has on the OSGrid, 'UCI Welcome', but you could use the actual name if you wish)

When I logged into my opensim, and opened the Map, I could now see the new link region at the 999 1005 location. Clicking in the middle of this new region, and then clicking the Teleport Button, I teleported directly to the region, and was able to explore the OSGrid from there. I teleported back home by selecting Teleport Home from the World menu on the viewer.

Important Note
Due to a viewer bug, you can only TP between regions that are no more than 4096 cells apart in any dimension. What this means in practice is that if you want to link to OSGrid, you must have your own regions reachable from the (10,000; 10,000) point on the map, which is where OSGrid is centered. Place your regions somewhere in the 8,000s or the 12,000s. If you don't, you will find that when you arrive at UCI Welcome all you will see is sky, no land, no avatars, and you will not even see yourself. However, if you turn your camera you will see the neighbouring sim, and crossing over into that you will then see yourself, with appearance intact. You might want to leave a marker pole on that sim, as others have done.

More details on Hypergrid and other regions that you could teleport to, are available on the Hypergrid wiki, from which this tutorial has drawn.

06. Connecting to the OSGrid

To connect a region or grid to the OSGrid you need to follow the steps below. However, it should be remembered that when you connect to the OSGrid you will be using their UGAIM servers, and they have no knowledge of you, or of any other users you may have created in your grid, nor of the builds you may have on your regions. All of your users will have to create accounts on the OSGrid, and they will lose all access to any inventory they may have while on your independent region or grid. You can get your builds over quite easily by using save-oar to save the prims on your regions, and using load-oar to bring them back in after connecting to the OSGrid.

If you have a well-established region or grid, with multiple users, then it may be a better solution to use Hypergrid to connect to the OSGrid, rather than a direct connection. See the Hypergrid tutorial for details.

Step 1. Create an Account on the OSGrid
Go to the OSGrid website, and click on Create Account in the left menu. Your avatar in the OSGrid will have the name you choose here, so choose wisely. Make a note of your OSGrid name and password, you will need these later.

Step 2. Find an Unused Region Name and Unused Location
You need to check if the name you want for your region has not been used by anyone else. So, choose Region List from the left menu. Whether it is free, or if you need to use another region name, make a note of your region name, you will need it later.

Next, click on Map on the left menu. It may be quite slow to load all the map. You are looking for a grid cell that is free, check to see if there is a small i for information symbol in a cell or not, if there isn't, then it is free. You then need to make a note of its grid location. To find this, click on the i symbol in some nearby cells, to see what their location is, and you will be able to work out the coordinates of the cell you want (I chose 9998, 10002). Make a note of the coordinates of your chosen location, you will need them later.

Step 3: Edit your Region File
You now need to make some edits to your region file in the Regions folder of OpenSim. Make a copy of this file somewhere safe first, in case you wish to revert later. Make the following changes (using your own region name and coordinates of course):

sim_name="WhateverYouLike" sim_location_x="9998" sim_location_y="10002"

Save the file

Step 4: Edit your OpenSim.ini File
You now need to make a few edits to your OpenSim.ini file (again, copy it somewhere safe first, in case you wish to revert later). Search for the following parameters, and change them as follows:

gridmode = true
asset_database = "grid"
see_into_this_sim_from_neighbor = True
serverside_object_permissions = True
grid_server_url = http://osgrid.org:8001/
grid_send_key = "1234"
grid_recv_key = "1234"
user_server_url = http://osgrid.org:8002/
user_send_key = "1234"
user_recv_key = "1234"
asset_server_url = http://osgrid.org:8003/
inventory_server_url = http://osgrid.org:8004/

Save the file.

Step 5: Launch OpenSim
You do not need the UGAIM servers for connecting to OSGrid, so you can now just go right ahead and launch OpenSim.exe You may see lots of errors rushing by in yellow and red, this is to be expected, but hopefully, the server should eventually complete, pause, and you will have the Region #: prompt. This indicates that your server is now connected to the OSGrid!

Step 6: Connecting your Viewer
Open your hippo viewer, select the Grids button, and choose OSGrid from the Select a Grid drop-down box. You might want to select this as the default from now on, if you expect to be on OSGrid for some time. Next, login using the User Name and Password that you chose when you created your OSGrid account earlier. You may now even see your region listed in the Region list on the main screen, if you do, select it. If not, then for the Start Location, choose and type in the name of your region.

If you are using the SL Viewer, use this at the end of the Target for the login URI: -loginuri http://osgrid.org:8002 -loginpage http://osgrid.org/loginscreen.php -helperuri http://osgrid.org/

Hit Connect, and you should be in your region on the OSGrid.

05. Working in Grid Mode

Up to now, I have had my OpenSim region operating in Standalone Mode. It is now time to get it working in Grid Mode, in readiness for connecting to the OSGrid. I had a few problems getting this mode to work, but advice from Jenni in the #opensim irc channel had me up and running in no time. Here is the finished working procedure:

Step 1. Configure Opensim
Make a copy of your OpenSim.ini file, and rename the copy to OpenSim.ini.standalone (so you can go back later if you wish). Open your OpenSim.ini file, and in the [Startup] section make gridmode=true, then in the [Network] section change the following keys from 'null' to '1234' as follows: grid_send_key = "1234" grid_recv_key = "1234" user_send_key = "1234" user_recv_key = "1234" Save the OpenSim.ini file.

Step 2. Launch the UGAIM Services
In the bin folder, locate the following 5 server services, named the UGAIM services, after their initial letters:

OpenSim.Grid.UserServer.exe
OpenSim.Grid.GridServer.exe
OpenSim.Grid.AssetServer.exe
OpenSim.Grid.InventoryServer.exe
OpenSim.Grid.MessagingServer.exe

Starting with the first (and the order is important), double-click to launch it. The console will pause to ask you some questions. You can accept the defaults for all, except the following:

Answer 1234 for all questions involving keys

Database connection string should look like this:
Data Source=localhost;Database=opensim;User ID=root;Password=xxxxxxx;

Note: I would type this database connection string out in advance, in notepad, then copy it to the clipboard, as you will have to paste this in to each of the 5 consoles, and will save you some work). Don't forget the final semicolon!

The UserServer will then generate an xml file (UserServer_Config.xml) with these settings in, which you can open in Notepad and edit. I only wanted to change the default_startup_message="Welcome to OGS" to "Welcome to Anubia"

Then start each of the other services, in the order given, accepting all the defaults, except answering 1234 for all questions involving keys. As with the UserServer service, xml files will be generated for each service.

Step 3. Launch OpenSim.exe.
When it has finished loading, you can connect.

Step 4. Configure the Viewer
To connect to your region in gridmode, you must make a change to your viewer. In SL, change the port number at the end of the Target from 9000 to 8002. Similarly, if you are using Hippo, go into Grids, select your grid (region) and change the Login URI port number from 9000 to 8002. You are now ready to connect.

Strangely, I failed to connect at first. On the second attempt (after a full restart of all the above services) I then got in, but only for a couple of seconds before the viewer crashed. Restarting the server services once more, and logging in with my viewer produced, 'You are already logged in' messages, but I persisted and kept trying to login, and restarting everything. Curiously, on the third or fourth attempt, everything worked, and I was in!

Reverting
If you wish to revert to Standalone Mode, rename the OpenSim.ini file to OpenSim.ini.gridmode, and rename your OpenSim.ini.standalone file back to OpenSim.ini. Then change your Port number on your viewer from 8002 back to 9000, and you should be good to go (but again, strangely, it took me 2 or 3 attempst to get back in properly). You do not need to change any of the keys from '1234' back to 'null'.

The next tutorial will show you how to connect to the OSGrid.

04. Migrating to MySQL

The OpenSim binaries to date have all been based around the SQLite database system, for managing assets, inventory, users etc. Unfortunately, this does not lend itself well to persistance (the ability to close down your viewer and your server, then start them back up again and find your appearance is back to the dreaded 'Ruth'). The solution to this is to use the MySQL database system, and this article will show you how to do that.

Step 1: Install MySQL
Download MySQL from here. I chose the Windows ZIP/Setup.EXE (x86) version (of course if you're running a different system you would pick the appropriate binary for your system). Unzip the package, and launch the Installer using the Typical setting.

Step 2: Configure MySQL
When it has finished installing it will take you through the Setup Wizard to Configure MySQL, choose Standard Configuration. On the next page of the Wizard ensure that 'Install as a Window Service', 'Launch the MySQL Server Automatically', and 'Include Bin Directory' are all checked. The next page is for your security settings. The modify Security Settings should be checked. Leave the 'Current Root Password' box empty, and put your own password into the 'New Root Password' box, and confirm it in the next box. Remember the root password that you choose!!! Write it down somewhere. If you lose this you will not be able to use or reinstall MySQL. Click on the Next, and then the Execute buttons.

MySQL is now installed. We next need to set up a database for MySQL and OpenSim to use.

Step 3: Create the Database
Go to Start, Programs, and you should see the new folder for MySQL, and the MySQL Server 5.0, launch the MySQL Command Line Client. Type in your password, and then at the mysql> prompt, type:

create database opensim;
quit;
(and don't forget the ending semicolons!)

The database has now been created, ready for use by Opensim. We now need to modify the OpenSim.ini file to tell it to use the new database.

Step 4: Save your Existing Objects
If you don't have existing objects in your regions you can skip this step.

Before changing over to MySQL you may want to save all the objects you have in your regions, and restore them after the migration. To do this you must save the objects from each region separately. Suppose you have two regions, called Alpha and Beta. The procedure is to use the following commands in the opensim server console:

change-region Alpha
save-oar c:\Alpha.oar

change-region Beta
save-oar c:\Beta.oar

and so on, if you have more regions.

Note: Do NOT try to do a save-oar while the region is Root, always change the region to the one you want to work on by using the change-region command first.

Step 5: Configure OpenSim
Go to the Opensim Bin folder, and in there you will find the Opensim.ini configuration file. Double-click it and it should open automatically in Notepad. You need to change the following lines (note: placing a semicolon(;) at the start of any line disables it by commenting it out, removing the semicolon enables the line):

Under the ; ## STORAGE section look for the line that says (; --- To use sqlite as region storage:) Make sure that the plugin and connection lines are commented out, thus: ;

storage_plugin = "OpenSim.Data.SQLite.dll" ; storage_connection_string="URI=file:OpenSim.db,version=3";

Then look for the line that says (; --- To use MySQL storage, supply your own connectionstring (this is only an example):) And uncomment out the plugin and connection lines, thus:

storage_plugin="OpenSim.Data.MySQL.dll"
storage_connection_string="Data Source=localhost;Database=opensim;User ID=root;Password=XXXX;"; (replace the XXXX above with the password you use for MySQL)

Next, go down to the [StandAlone] section, and in the Asset Database provider, make sure that only MySQL is uncommented, thus:

;asset_plugin = "OpenSim.Data.SQLite.dll"
asset_plugin = "OpenSim.Data.MySQL.dll"

User Database provider should all have ONLY the following uncommented, respectively: asset_source = "Data Source=localhost;Database=opensim;UserID=root;Password=XXXX;" inventory_source = "Data Source=localhost;Database=opensim;User ID=root;Password=XXXX;" user_source = "Data Source=localhost;Database=opensim;User ID=root;Password=XXXX;" again, replacing the XXXX with your MySQL password. Do make sure that the SQLite source lines are commented out, thus:

; asset_source = "SQLiteDialect;SqliteClientDriver;URI=file:Asset.db,version=3"
; inventory_source = "SQLiteDialect;SqliteClientDriver;URI=file:Inventory.db,version=3" ; user_source = "SQLiteDialect;SqliteClientDriver;URI=file:User.db,version=3" Save the Opensim.ini file.

You should now be fit to go. Start the opensim server, and all the necessary databases will be created for you by MySQL.

Step 6: Restore your Objects
This step only applies if you previously saved your objects in Step 4.

To restore your objects that were saved in Step 4 above, you use the following commands, and again, assuming that you had two regions called Alpha and Beta.

change-region Alpha
load-oar c:\Alpha.oar

change-region Beta
load-oar c:\Beta.oar

You should now have all your objects back as they were before the migration.

03. Remotely Connecting to a Standalone Sim

OK, so you have successfully installed the OpenSim standalone sim and you are wandering around in your own little world. Exciting times indeed, but after a while, with only yourself for company, you start to miss the social interaction of Second Life. So, what's the solution? Invite someone over!

I would recommend to access your sim remotely, before you start thinking of connecting your sim to a grid, in this way you can give the details to a friend or friends and invite them in to have a look at your brave new world, before you open up your sim to the wider metaverse. So, how do you do it?

Step 1: Ensure your PC has a static IP address
It is essential that the PC you have your sim on has a static IP address. To find out whether your PC has a static (permanent) IP address, or whether it is dynamically assigned (meaning it can change from day to day) by either a router or your Internet Service Provider (ISP), do this:- Go to Start, and select Run..., type 'cmd' into the Open box, and hit OK. When the DOS window opens, type the command ipconfig/all. If you see a value that says DHCP disabled, it means that your PC has a static IP address, and you can move to the next step. If it says DHCP enabled it means that the IP address is being supplied either by your router (if you have set up a home network, or LAN), or if you do not have a router, by your ISP. To change to a static IP if you have a router follow the procedure provided here. If you have no router and have a direct connection to the internet, then skip to Step 2.

Step 2: Ensure your Firewall can pass the required Ports
If you are connected directly to the Internet, either through a dial-up service or via ISDN or ADSL, then you will probably have a software firewall set up. You will need to read your firewall documentation to see how to allow the ports that OpenSim uses to pass through the firewall. If you use a router with an in-built hardware firewall, then you need to configure the router to pass the required ports (called port-forwarding). The ports that OpenSim needs to be open for inbound traffic are: TCP/8000-8005, TCP/8895, and UDP/TCP/9000 for a single sim, and UDP/TCP/9001 for a second sim, and so on. There are detailed instructions on how to setup port-forwarding on your router on the PortFowarding website. Select your router from the list, then you will be taken to a page that lists most on-line games that need port-forwarding. At present, neither OpenSim not OpenLife are listed (although a listing has been requested), so the next best one to choose is Well of Souls, which also uses port 8000, and you can follow the procedure there for setting this one up, then repeating for the other ports listed above.

Step 3: Setup a Dynamic DNS Service
Most ISPs provide their customers with a dynamic IP address for their connections (static IP addresses are mostly used by commercial customers). If you connect to the internet directly without using a router, then your PC will have its IP address allocated via DHCP by the ISP. If you have a home LAN behind a router then the ISP will provide the IP address via DHCP to the router instead. In either case we must establish a static IP address (or rather the appearance of a static IP address), and that is where Dynamic DNS comes in. A very good explanation of what DNS and Dynamic DNS are is provided here. Basically, instead of having an IP address for your PC or router, such as http://79.234.23.06/ (which may change daily), you have a domain name, such as http://garys-sim.servegame.org/ (which does not change). So, how does the domain name know which IP address to resolve to? Dynamic DNS hosts are kept up-to-date automatically with the IP address supplied by your ISP, using an update client. Update clients come in two types: software clients, which are installed on your PC, or hardware clients embedded in devices such as routers. Software clients are easier to set up than hardware clients, so I recommend the free client from the dynDNS.com website, called DYNDNS Updater. Obtaining a DNS host name is simple, and free, from this location

Step 4: Configure your OpenSim Software for an external Connection
The next step is to configure the OpenSim software. To do this go to the Bin/Regions/default.xml file. Right-click and Open with Notepad. The value to change is the external_host_name, which can be your DNS host name, so it will look like this: external_host_name="garys-sim.servegame.org"

Step 5: Configure the Viewer
The last step is to configure the viewer. Ensure that the Hippo viewer Loginuri: is set to the same URL as the external_host_name above (but qualified with http:// and the port number), i.e.
http://garys-sim.servegame.org:9000. If using the SL viewer ensure that the Target is pointing similarly, i.e. -loginuri http://garys-sim.servegame.org:9000

You are now ready to test. Start up the opensim server, and when it is ready, connect with your viewer.

Troubleshooting

Followed all the above steps and still cannot connect remotely? Try these faultfinding steps:

1. In case it is the hostname that is causing the problem try using the external (router) IP address instead. Open a browser and go to this URL: www.checkmyip.com this will tell you what your external IP address is (eg: 78.154.28.7). Put this address into the default.xml file, like so: external_host_name="78.154.28.7"

If that fixes it, then go to the DYNDNS website and check that the IP address currently assigned to your hostname matches what www.checkmyip.com tells you. If it doesn't then maybe the updater software is not working. Try reinstalling it.

2. Firewalls and antivirus software can stop a connection from being made. If you have a router then it will already have a hardware firewall built in, so it is usually quite safe to switch off your other firewalls, such as Windows Firewall, ZoneAlarm, or any of your security suites that may have a firewall bundled. So just try switching them all off and then see if a connection can be made.

3. Try to ping your external IP address. Go to Start, and in the Run box type cmd to get the DOS-like cmd console up. In here type (using the example above): ping 78.154.28.7

If you get a response fine, but if the three attempts all time out then either your router is setup to ignore pings, or your ISP is blocking them. If your router manual provides no info on blocking pings, then try asking your ISP support if they block them.

4. The most common reason I have found for not connecting has been that the router was not configured correctly to pass the required ports. Please double-check that you have gone through Step 2 100% correctly.

If you had a problem connecting, and eventually got it resolved, please post your solution here, it may help others.

02. Connecting two Viewers to your Region

Now that you have your standalone sim up and running, and after the initial euphoria has worn off, you may have noticed how lonesome it is in there. But before you invite someone to join you in your sim (which is a little involved, but hopefully explained clearly in the next tutorial), you might want to check that you can connect two viewers to your sim locally, both from one computer, and then from two computers (if you are using a home router). This is how to do it:

Step 1: Set the External Host Name
In your Bin/Regions folder you will find the default.xml file, right-click it and select Open With, and choose Notepad. The value you are looking for is external_host_name="127.0.0.1". The value in the quotes is the IP address of the computer running the OpenSim server software. An IP address of 127.0.0.1 is a special reserved address, and basically means THIS computer. We now need to be a bit more specific and refer to the server computer by its actual IP address. To find this out, go to Start, Run, and type 'cmd' (without the quotes) in the Open: box. A DOS window will open. Now, type the command IPCONFIG/ALL and hit Enter. This will reveal your machine's IP address. Make a careful note of this. A typical IP for a PC on a home LAN will have an address similar to 198.168.0.2 (the router normally has a LAN-side IP address of 198.162.0.1). But, whatever the IP address has been reported, enter it within the quotes following the entry external_host_name=, so it looks something like this: external_host_name="198.162.0.2"

Step 2: Have two Viewers Installed
I hope you have a copy of the Second Life viewer and the Hippo viewer as I recommended in Tutorial 1 of the series (the link is there too).

Step 3: Create a Second User
Start the OpenSim server software, and when it has completed its startup and is ready you can then add another user. To do this, type the following command at the bottom of the server (DOS-like) window:

create user John Doe test 1000 1000

This command will create a new user, called John Doe (but this name can be anything you like), the password is 'test', but again, choose whatever you like. The X and Y coordinates should be the default 1000 1000, as you did when setting up the first user.

Step 4: Login Both Users
Start your first viewer, and use the login details of your first user, and Connect. You should be in. Start your second viewer, and use the login details of your second user. With any luck and a fair wind, you should now have two avatars in your region (but both occupying the same space, so move one of them).

Step 5: Login Both Users from two PCs
If you are using a home router, and have more than one PC on your home LAN, then you can try logging in two users from two different PCs. Simply install a viewer on the second PC If you are using the Hippo viewer, Add a new grid as explained in Tutorial 1, and change the loginuri to the same IP address as the external_host_name entry above, and of course follow it with the :9000 port number, so it looks something like this http://192.168.0.2:9000/.

If you are using the SL viewer change the target in the shortcut icon to look something like this:

"C:\Program Files\SecondLife\SecondLife.exe" -loginuri http://192.168.0.2:9000/

Now login with the two viewers on the two PCs, using the two user accounts created. I would wait until one of the users is successfully logged in before attempting to log in with the other user on the other PC.

In the next in the series, I will explain how to log in to your standalone sim remotely.

01. Installing OpenSim

In order to setup a basic standalone sim on your home PC you need just two pieces of software, the OpenSim server software, and a client (viewer) to connect to it.

Step 1: Installing and Setting up the Server
The OpenSim server software can be downloaded from the OSGrid website. While on the OSGrid download page, I recommend that you also download the new Hippo viewer, especially designed for grid use, and with a very nifty new Grid button. It supports 45,000 prims and allows building up to a height of 10,000 m. Megaprims of up to 256x256x256 m come as standard, and it has several other exciting features. You can, of course, use the SL viewer, and this tutorial will guide you through using both the Hippo viewer and the SL viewer.

Once you have downloaded the OpenSim server software, unzip it, and get the Bin folder out. This folder contains all the files needed for the OpenSim server. This folder can reside anywhere you like on your hard-drive. The steps required to get the server ready for use are as follows:

  1. Create a shortcut on the desktop to the OpenSim.exe file in the Bin folder.
  2. Rename the opensim.ini.example file to OpenSim.ini, and made sure that you are in standalone mode by going to the [Startup] section, and setting gridmode=false (if you intend to connect your region to a grid, such as OSGrid, you will need to set this to true, but for now, practice with a single standalone region). (Note: Vista users should ensure that they are in Admin mode, before completing the next steps)
  3. Double-click the OpenSim desktop shortcut and a DOS-like server control window will open, and various status messages will scroll by. Once it has stopped it will ask for the basic 9 settings it will use to create your first region, with the default settings in square brackets. To accept a default setting, just hit the Enter key:

    Region Name [openSim Test] name your region here, anything you like *
    Grid Location (X-Axis) [1000] do not change
    Grid Location (Y-Axis) [1000] do not change
    Internal IP address [0.0.0.0] do not change
    Internal IP Port [9000] do not change
    External Host Name [127.0.0.1] keep, for now *
    First Name of Master Avatar [Test] change to whatever you like *
    Last Name of Master Avatar [User] change to whatever you like *
    Password for Master Avatar [test] keep or change to whatever you like *

All the parameters marked * you should make a note of, as you will need them later when setting up your viewer.

After entering the last parameter the Server creates the default.xml file in the Bin\Regions folder, and when you see the line,

Region (root) # :

you know the server is ready.

Step 2: Installing and Setting up the Hippo Client (Viewer)

One of the nice things about the new Hippo viewer is that you do not need to mess about with changing the Target in the shortcut's Properties. Instead, launch the Hippo viewer, and you will notice a new Grids button, next to the Connect button. In here you can choose which grid to connect to, add new grid details, etc. Let me walk you through setting this up for your own region you just created.

  1. Click on the Grids button, you will see in the 'Select a Grid' drop-down box that connection details to 3rd Rock, openlife, osgrid and secondlife have already been set up. So, to create your own, click on the Add button. Set the details as follows:

    Loginuri: http://127.0.0.1:9000 (this is the External Host Name parameter and Port)
    Platform: Opensim
    Grid Nickname: same as the Region Name in the server setup above
    Grid Name: same as the Grid Nickname
  2. Click on Apply. If you want your region to be the default region that Hippo connects to when it starts up (rather than the current default grid of osgrid, just choose your region from the Select a Grid drop-down box, and click the Default button.

Ok, you are now good to connect to your sim. Enter the Master Avatar details you provided earlier to the server, and click on the Connect button. You should now be standing in your very own standalone sim!

Step 3: Setting up the SL Client (Viewer)

If you already have SL installed on your PC, and have a shortcut icon to launch it on your desktop, then configuring it to connect to your standalone sim is straightforward.

Right-click the shortcut and choose Copy. Right-click on the desktop and choose Paste. Rename the new shortcut to Opensim or the name of your first region.

Right-click the new shortcut and choose Properties. On the General Tab you will see a text box labelled Target. Go to the end of the text in this box, insert a space, then type the following:

-loginuri http://127.0.0.1:9000/

Click on Apply, then OK.

You can now log in with the Master Avatar details you provided earlier to the server, and click on the Connect button. You should now be standing in your very own standalone sim!