The Complex Set of Initialization Files to Run OpenSim

The Complex Set of Initialization Files

All the *.ini files are text files for storing parameters for a software system. In the case of OpenSim there are thousands of parameters that must be set up in a half a dozen different files.

Every OpenSim system has a Robust.exe program running as the central controller of the system. Robust keeps the asset database of all the assets in the system, all the user accounts and several other services. When a region connects up to a remote grid like OSGrid, the administrators of OSGrid run Robust for you and you don't have to worry about it. But if you are creating your own grid, you will be running your own copy of Robust and must set up two files to tell it all about your grid.

Normally for every region you will run a separate 'instance' of the OpenSim.exe program. (It is possible to run several regions under one instance, but this is not recommended except for low usage regions like oceans). OpenSim.exe keeps the terrain for a single region and a database of all the items rezzed in it. It also runs scripts, handles physics, keeps track of visiting avatars and keeps a cache of recent assets so it doesn't have to refer to the Robust asset server for items seen before.

There is a complicated tree of initialization files that you have to set up to tell OpenSim about your system and region. I’ll show you how it works out of the box, however I don’t recommend you use this as is! I’ll show you how I have re-organized all this in a better way. Then I’ll run through every line of every INI file that you need to edit to get your grid up.

The Default Organization of the OpenSim INI files:

OpenSim.exe is one file in a 'bin' folder full of libraries and folders of default assets. You can run it from another location and tell it where to find all the other crap in bin, but it is easiest to just give in and run it from the bin folder.

When OpenSim.exe starts up, it reads a file named OpenSim.ini to get module names, port numbers, URLs and 1000's of other parameters. "The code is the documentation", in this case meaning the developers say you must read OpenSimDefault.ini and OpenSim.ini where there are a lot of comments telling you what some of the parameters are. Often the comments are even correct. I find the organization of this file to be terrible. It is buried down in the bin folder between lots of other files you should not touch. The Parameters that you must change for each region are scattered through the file. Things that are constant for every region in the grid are scattered through this file and another file named GridCommon.ini. It is annoying that many settings that are common to the grid are NOT in the GridCommon.ini file! The OpenSim.ini file assumes that several things, including the GridCommon.ini file are in a sub-folder of bin named config-include. Each region instance has a Regions.ini file that MUST be in a separate folder under the bin folder. Region.ini files are read in a separate pass that cannot share settings with OpenSim.ini, and there are settings you you MUST duplicate in these two files or things will not work! Files that are included inside other include files must be named under the assumption that they are read from the starting directory, usually bin. The code that reads these INI files will let you over-write settings in files read later, but if settings appear twice in one file, the second copy is ignored.

The OpenSim developers recommend reading the OpenSim.ini file carefully every time a new release comes out. This is a mind numbing job that takes hours to check and make sure your settings are transferred to all the places they should be. It doesn't help when the developers make big changes to the INI files and you can't use DIFF to find your own settings. But they sometimes add new sections that you must define, so it is imperative to look for differences.

I'm going to suggest a better way to organize these files, but first here is the order that OpenSim normally reads all the INI files:

bin/OpenSimDefaults.ini

| addon-modules/*/config/*.ini

bin/OpenSim.ini

| config-include/osslDefaultEnable.ini

| | osslEnable.ini

| config-include/GridHypergrid.ini

| | GridCommon.ini

| | FlotsamCache.ini

Regions/Regions.ini

The OpenSimDefaults.ini file is read first and sets all the default values. You are not supposed to ever edit this file! It goes on a fishing expedition looking for INI files for addon-modules. I make sure this folder is empty, so this doesn't cause me problems! Then the OpenSim.ini file is read, and it is allowed to over-write any values set by default. It loads osslDefaultEnable.ini from the config-include folder and you are not supposed to change anything in that file. That file loads the osslEnable.ini file from the same sub-folder, and in there you are allowed to over-ride any of the OSSL permission settings. Back to the OpenSim.ini file, it loads the GridHypergrid.ini file in config-include, which you are not supposed to ever change. It in turn reads your GridCommon.ini which reads your FlotsamCache.ini file. OpenSim.ini doesn't actually read the Regions.ini file, but it sets the folder name where region files are searched for later. The default is to expect the Regions folder to be under the bin folder. OpenSim goes on a fishing expedition and reads any INI files it finds in the Regions folder, so you cannot store any other INI files in there.

In my INI organization, described above, I have a folder hierarchy that starts with a Grid folder with many grid common files. These are used by INI files farther down in the tree. Then there is a Grid/Regions folder that has a ‘base’ folder for every region. Each region folder has its own bin folder and another Regions folder to put the Regions.ini file in. I’m sorry that there are two layers of folders named Regions that do different things.

The files you will need to edit the first time are:

Robust.ini	after copying it from Robust.ini.example
Robust.exe.config
OpenSim.ini	after copying it from OpenSim.ini.example
OpenSim.exe.config
osslDefaultEnable.ini	after copying it to the Grid folder
osslEnable.ini	after copying it to the Grid folder from osslEnable.ini.example
GridHypergrid.ini	after copying it to the Grid folder
GridCommon.ini	after copying it to the Grid folder from GridCommon.ini.example
Local.ini	a file I added for local parameters for each region

Later when you add your 2nd region, you will only have to edit two files, and the changes will be few, quick and easy!