Deploying OpenSim on Windows Server 2008

This article was written at work, but I thought it might be of use to current and potential OpenSim users :-)

Lates OSGrid Binaries are available from their website.

Requirements

  1. MySQL (ftp://ftp.mirrorservice.org/sites/ftp.mysql.com/Downloads/MySQL-5.5/mysql-5.5.8-win32.msi used)
  2. OpenSim (http://download.osgrid.org/osgrid.opensim-01262011.v0.7.1.c472764.zip used)
  3. The IP address of the machine that OpenSim is being installed on.

Installation

MySQL

  1. Start the installer
  2. Click "Next"
  3. Accept the GPL EULA, then click "Next"
  4. Select "Custom" setup type (this is a good habit to get into when installing software, to prevent useless crud being installed)
  5. Ensure all required components will be installed, then click "Next"
  6. Click "Install"
  7. System Administrator permissions may be required at this point
  8. Select "Detailed Configuration"
  9. Select "Server Machine"
  10. Select "Multifunctional Database"
  11. Specify location (default of "C:\MySQL Datafiles\" is usually fine)
  12. Unless there is going to be a large number of regions (mid-high double figures & upwards), the default "Decision Support" option should be sufficient
  13. Strict mode should remain enabled. Unless security policies dictate otherwise, specify "Enable TCP/IP Networking" and port number "3306"
  14. Specify "Best Support for Multilingualism" (UTF-8)
  15. Install as Windows Service, service name MySQL, launch automatically
  16. "Include Bin Directory in Windows PATH" is optional, but may come in handy when administering the database from the command line.
  17. Once installed, setup a user & database for OpenSim to make use of.
    1. Open a command line window
    2. Log into the MySQL shell via "mysql –user=root –password=whateverItWasYouConfiguredEarlier"
    3. CREATE DATABASE opensim;
    4. CREATE USER ‘opensim’@'localhost’ IDENTIFIED BY ‘somethingDifferentToTheEarlierPassword’;
    5. GRANT ALL PRIVILEGES ON opensim.* TO opensim@localhost IDENTIFIED BY ‘thePasswordYouJustEntered’;
    6. FLUSH PRIVILEGES
    7. quit

OpenSim

  1. Create a folder on the C drive named OpenSim
  2. copy the /bin/ folder from the OpenSim zip file to the OpenSim directory.
  3. Rename the folder according to the version of OpenSim, as this helps quickly rolling back to a previous version should there be any problems.
Robust.ini
  1. Open Robust.ini.example from the renamed /bin/ folder in a text editor such as "Notepad++", and save as "Robust.ini"
  2. In the DatabaseService section, change the "Database", "User ID" and "Password" parameters of the "ConnectionString"
  3. Optionally, change the "WelcomeMessage" string to something more appropriate.
  4. Change the values in the "GridInfoService" section to something appropriate. The port number should be set to 8002.
  5. Start Robust.exe to ensure there are no errors in configuration.
  6. If successful, type "quit" and press enter to close the process.
/config-include/GridCommon.ini
  1. Comment out the Include-Storage line for SQLite
  2. Uncomment the MySQL parameter line, using the same parameters specified in Robust.ini for the ConnectionString
  3. Change all URI parameters to http://whateverTheIPAddressIs:8003
Create a blank slate for deploying island clusters
  1. In C:\OpenSim\, create a folder named "IslandClusters"
  2. Create a folder named "blank-slate", with three sub-folders named "backup", "crashes" and "regions"
  3. Create a file named "shutdown.txt" with only the word "backup" contained within
  4. Save a copy OpenSim.ini (or OpenSim.ini.example) to C:\OpenSim\IslandClusters\blank-slate\OpenSim.ini
  5. In the "Startup" section;
    1. Specify crash_dir as "C:\OpenSim\IslandClusters\blank-slate\crashes"
    2. Specify startup_console_commands_file as "C:\OpenSim\IslandClusters\blank-slate\startup.txt"
    3. Specify shutdown_console_commands_file as "C:\OpenSim\IslandClusters\blank-slate\shutdown.txt"
    4. Specify regionload_regionsdir as "C:\OpenSim\IslandClusters\blank-slate\regions"
    5. Alter TextureOnMapTile to true
    6. Alter/uncomment see_into_this_sim_from_neighbor to true
    7. Alter/uncomment MaptileRefresh to 3600
  6. In the "Network" section, Alter/uncomment http_listener_port to 10000
  7. In the "Messaging" section, disable (comment out) all options.
  8. In the "DataSnapshot" section, disable (comment out) all options except for "gridname"- change that to the short grid name specified in Robust.ini
  9. In the "Search" section, disable (comment out) all options.
  10. In the "Profile" section, disable (comment out) all options.
  11. In the "XEngine" section, change "AllowOSFunctions" to false
  12. In the "Groups" section, disable (comment out) all options.
  13. Create a new shortcut to OpenSim.exe in the renamed /bin/ folder in "C:\OpenSim\IslandClusters\blank-slate", specifying the command line options as –inifile="C:\OpenSim\IslandClusters\blank-slate\OpenSim.ini"
  14. Zip up the folder to blank-slate.zip, then delete the folder.
Deploying an island cluster

It is important to keep track of port numbers used in islands, since they cannot be shared on the same machine.

Robust.exe should have been started prior to these steps.

  1. Extract blank-slate.zip to C:\OpenSim\IslandClusters
  2. Rename the resulting "blank-slate" folder to the name of the new island cluster
  3. Open OpenSim.ini in a text editor, and replace all instances of "blank-slate" with the name of the new island cluster folder
  4. Right-click the OpenSim shortcut, and change "blank-slate" in the command line arguments to the name of the new island cluster folder
  5. Double-click the new shortcut- if everything has been configured correctly, the OpenSim shell will eventually ask for a Region name.
  6. Most defaults can be accepted, by the co-ordinates cannot be shared by islands on the same grid, whilst port numbers cannot be shared by islands on the same server.
Adding content to the shared Library

It will be necessary to restart Robust.exe

  1. Create a folder named _libraries in C:\OpenSim\
  2. Create a sub-folder for the content.
  3. Place the folders.lib.xml, items.lib.xml and assets.lib.xml files in the new sub-folder.
  4. Create a sub-folder in the content folder named assets.
  5. Place all assets in the assets sub-folder.
  6. Open inventory/Libraries.xml from the renamed /bin/ directory.
  7. Duplicate the last <Section> block in the file, altering the duplicate’s Name attribute to correspond to the name specified in step 2
  8. Update the Value attributes in the two <Key> elements to the absolute path to the folders.lib.xml and items.lib.xml files
  9. Open assets/AssetSets.xml from the renamed /bin/ directory.
  10. Duplicate the last <Section> block in the file, altering the duplicate’s Name attribute to correspond to the name specified in step 2
  11. Update the Value attribute in the <Key> elements to the absolute path of the assets.lib.xml
Windows Firewall with Advanced Security

In order to allow people to connect to the OpenSim grid, at least 3 inbound firewall rules will need to be created.

Windows Firewall does not currently provide the rule creation window with an interface for specifying port ranges (although you can provide a comma separated list of port numbers), nor does it allow you to provide an interface for specifying multiple protocols. Rather than selecting "Any" protocol, separate rules should be created for both TCP and UDP protocols.

It is suggested that one pair of rules be created for each island cluster, to make managing the rules easier in the long-term.

  • Robust.exe needs ports 8002 & 8003 over TCP
  • For reach island, Opensim.exe needs access to the port number specified during deployment over both TCP and UDP.
  • If the Robust rest console is to be used, a TCP port needs to be opened on the number specified by "ConsolePort" in the Network section of Robust.ini

Upgrading

While the OpenSim wiki contains instructions on upgrading Opensim, our deployment process differs to the default.

Don’t forget to backup the OpenSim database by bringing up a command prompt window, and type mysqldump -h localhost -u username -p opensim > c:\OpenSim\backup\opensim-YYYY-MM-DD_HH-MM.sql, where YYYY-MM-DD_HH-MM is today’s today and current time. You will be prompted for the password.

Updating Robust.exe & OpenSim common configurations

  1. As with installing OpenSim from scratch, extract the new version of OpenSim to a folder that is version-specific
  2. Review Robust.ini.example, OpenSimDefaults.ini, OpenSim.ini, config-include/Grid.ini and config-include/GridCommon.ini for changes made since the previous version. (Notepad++ comes in handy for this task, as it has a built-in document comparison tool).
  3. If there are no unexpected changes to the files, copy the Robust.ini, OpenSim.ini and config-include/Grid.ini files from the previous deployment to the new deployment folder. If there are changes, review them for integration or overriding.
  4. Test the configuration of the newer Robust.exe by launching it and checking for unexpected errors. Quit the process if it is successful.
  5. Copy any alterations from the old inventory/Libraries.xml and assets/AssetSets.xml files to the files in the new deployment folder. Do not simply copy the files as new libraries and asset sets may have been added to a newer version of OpenSim.
  6. Start the newer Robust.exe

Updating the blank slate

Steps 3,4 and 5 need to be repeated for each island cluster, but are written in the context of the "blank-slate" archive, since the blank slate also needs to be updated.

  1. Extract the contents of C:\OpenSim\IslandClusters\blank-slate.zip to C:\OpenSim\IslandClusters\blank-slate\
  2. Rename C:\OpenSim\IslandClusters\blank-slate.zip to refer to the version of OpenSim it is meant for.
  3. Right click the shortcut to OpenSim in the blank slate folder and select properties.
  4. Update Target to reflect the location of the newer OpenSim.exe.
  5. Update Start in to reflect the directory for the newer deploy of OpenSim.
  6. Create a new zip file archiving the files in C:\OpenSim\IslandClusters\blank-slate\.
  7. Delete the blank-slate folder
This entry was posted in OpenSim and tagged , . Bookmark the permalink.

8 Responses to Deploying OpenSim on Windows Server 2008

  1. Pingback: Tweets that mention Deploying OpenSim on Windows Server 2008 – SignpostMarv's Blog -- Topsy.com

  2. hmmm now all I need is the finances to buy a server… LOL

  3. Thank you for compiling these instructions!

  4. This is a great list of instructions. I appreciate all the work you went to documenting your process. It certainly helped me.

  5. John Sheppard (Nielsen) says:

    Will this work on something other than Win 2008? I have Win 7 and would dearly like to use this.

  6. SignpostMarv says:

    Yes, it should be fine on Windows 7 (my dev machines at home & work are Win 7). I’d suggest looking at the more up-to-date guide too, btw http://signpostmarv.name/2012/08/25/deploying-opensim-on-windows-server-2008-r2/

  7. I gave up hope of being able to ever get Robust running ages ago. Until i saw your instructions for win 8 server and thought I would have another try , as I had a spare copy, as it happens I didn’t need it because as you say it works on win 7 just as well.

    Developers forget when they provide instructions to us non professionals that we are not as familiar with all the terms and tools and if they do not provide all these details they may as well not bother to provide anything.

    It would never work for me before, using notepad++ made all the difference.
    But I still had to go listen to a few vids of microsoft virtual academy to get my head around uncommenting it would help if someone explained which bits to cut out more precisely.

    I got there in the end by trial and error ..very trying and many errors

    Thanks very much appreciated !

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>