Editing the OpenSim.ini and other files

Setting Up a Folder for Your First Region

In my recommended hierarchy of folders for installing OpenSim, I have a folder (named Regions) that contains a 'home' folder for each region. Welcome is one of those folders, but you can name your welcome region anything you want. But the following example will assume the Welcome folder is already there. Logon to the OpenSim account and type:

   cd ~/Grid/Regions/Welcome
   cp -r ~/Source/OpenSim-Sasquatch/build/Release bin
   cp -r bin/Regions Regions		#move Regions out of bin!
   cp bin/OpenSim.ini.example bin/OpenSim.ini
   cd bin

This copies the Release folder from the Sasquatch OpenSim build into the bin folder. Then it grabs a copy of the Regions folder from bin and puts it in the home folder for this region. This has an example file documenting how to make the Regions.ini file later. Finally I copy the example OpenSim.ini file in bin to get ready for the next step.

Edit the OpenSim.ini File the First Time

I want to use the bin/OpenSim.ini file that comes from the developers with the fewest possible changes. So I edit JUST TWO LINES in it. First I change the Include-osslDefaultEnable setting to also go to the common Grid folder. Now it looks like this with a relative path that works from any bin folder:

   Include-osslDefaultEnable = "../ ../ ../osslDefaultEnable.ini"

Second I change the Include-Architecture lines down at the end of the file. Comment out the first Include-Architecture line and uncomment the last (Hypergrid) line. But instead of sending that into the config-include folder, I use a relative path from the bin folder up to where I put the GridHypergrid.ini file and all the other grid specific files. So now the Include-Architecture line looks like this:

   Include-Architecture = "../ ../ ../GridHypergrid.ini"

Everything else in the OpenSim.ini file can be ignored because they will all be over-written by files included later. Keep reading to see how to edit all of those.

Edit the OpenSim.exe.config File

This is another file that sends a log file back into the bin folder. I search for “OpenSim.log” and replace it with “../OpenSim.log” to get the log OUT OF THE BIN folder. Now every region has its own log in its base directory.

Edit the osslDefaultEnable.ini and osslEnable.ini Files

Yes the documentation, I mean the comments, say you are not supposed to change the osslDefaultEnable.ini file, but it was written assuming it was stored in the bin folder and after moving it up into the Grid folder, I had to make one change to correct for that. In osslDefaultEnable.ini I find the Include-osslEnable line and edit it to look like this:

   Include-osslEnable = "../ ../ ../osslEnable.ini"

You will then want to edit the osslEnable.ini to enable all the functions you want to allow on your grid. How do you know how to do that? “The code is the documentation”: Read the osslDefaultEnable.ini to see all the possible functions, copy lines from there into osslEnable.ini and change the permissions. This sets things up for all regions to have the same functions enabled. If you want this to change in some regions, read on there is a way to do that.

Edit the GridHypergrid.ini File

Again, you are not supposed to edit GridHypergrid.ini but after moving it up 3 folders in the hierarchy, you have to change an Include line for it to find the GridCommon.ini file. I make one change to GridHypergrid.ini that looks like this: Include-Common = "../ ../ ../GridCommon.ini"

Edit the GridCommon.ini File

I’ll step through GridCommon.ini one line at a time below, but there are so many changes that the smartest thing to do is to find a working copy and modify it only slightly for your grid. I will put one in the Wiki someplace for you to copy. Here is what we are about to do to it:

I copy all the lines in the OpenSim.ini that I normally have to change for my grid, and I put them in my GridCommon.ini file. (DUH! Why are they not there already?) The default GridCommon.ini loads FlotsamCache.ini, but for my fsassets setup there are only a few lines in FlotsamCashe.ini that are needed, so I just moved those lines into GridCommon.ini. One of those lines tells the system where the region CasheDirectory is located. I put that in a Data folder that is shared by all the regions. I put it outside of the whole Grid folder to avoid many problems mentioned elsewhere in this document. There are several other data folders that I also change in the GridCommon.ini file. These all default to sub folders in bin and I want to get them out of there! The folder settings that I change are fsassetd, ScriptEnginesPath, MapTileDirectory and snapshot_cashe_directory. I send them all to a distant Data folder. Also in this GridCommon.ini file, I set the location of the folder for Regions.ini to "../Regions". This moves it up into the folder for the specific region, while still allowing me to use the one common GridCommon.ini file on all regions. While I'm at it, I use the same relative location for the pid file to move it up to "../pid" so it lives in the home folder for the region. At the very end of GridCommon.ini, I add a line that includes the Local.ini file that has just the things ‘local’ to each region.

Which lines should you include from OpenSim.ini in the start of GridCommon.ini? I will have a sample copy for you to start with. For completeness I stuck my notes below with all the changes made to GridCommon.ini, but I don't recommend you step through these and make the changes yourself. You could only copy the ones you want to change, or all the ones you think you might like to set once for the whole grid, or just copy all of OpenSim.ini up to but not including the [Architecture] section. Many of the sections have good defaults and you don’t need them, but it can’t hurt to have them in the Grid common files. I was tempted to then delete them all from OpenSim.ini, but that is the file most often changed by the devs, and every time I update to a new version of OpenSim I want to grab the whole OpenSim.ini to make sure I get those new Additions.

List of Changes to GridCommon.ini

Change the BaseHomeName to your grid URL (without the http://)
Change the PublicPort to 8002, or whatever port you are using.
Check that the PrivatePort is 8003 or whatever you are using.
In the [Startup] section, uncomment and change the PDIFile to “../pdi” to get it out of binaries 
Uncomment the regionload_regionsdir to “../Regions”
Uncomment the meshing = ubODEMeshmerizer line
Uncomment the physics = ubODE line
Uncomment the DefaultScriptEngine = “YEngine” line. (Xengine is being removed soon)
Add the following lines to the [Startup] section:
   UseCSJ2K = false	;OpenJPEG if false, UseCSJ2K is slow and generates errors on console
   		; Kayaker: Values recomended by Balpien for tuning OpenSim.
    	FrameTime=0.04546                  ;halve this to double the frame rate
    	UpdateTerrainEveryNFrames = 150    ;double this to match
    	Normalized55FPS = false;           ;report true frametimes
In the [Map] section, uncomment MapImageModule and change to "Warp3DImageModule"
Uncomment GenerateMapTiles and set to false.
   (comments are wrong, false means just don’t generate them every region startup)
Uncomment RenderMeshes and set to true.
Add the following lines to the [Map] section:
       RenderMaxHeight = 2048
       RenderMinHeight = -1
In the [Permissions] section uncomment region_owner_is_god and set it to false
Uncomment simple_build_permissions and set it to true
In the [Estates] section, uncomment DefaultEstateName and DefaultEstateOwnerName, choose names
In the [Network] section, change the shard, sometimes that is used as the grid name
In the [Messaging] section, uncomment OfflineMessageModule = "Offline Message Module V2"
Uncomment the StorageProvider = OpenSim.Data.MySQL.dll line
Uncomment the MuteListModule = MuteListModule line
Uncomment the ForwardOfflineGroupMessages = true line
Add the following line to the [messaging] section:
   Gatekeeper = "${Const|BaseURL}:${Const|PublicPort}"
REMOVE THE SECOND [Messaging] section near the end of the file.
In the [ODEPhysics] section add this line:
    world_stepsize = 0.022727          ;Balpien: halve this to double the physcis frame rate
In the [YEngine] section uncomment the Enabled line
Uncomment and set the MinTimerInterval to 0.05
Uncomment and set the ScriptDistanceLimitFactor to 10.0
Uncomment and set the ScripEnginesPath to “../ ../ ../ ../Data/ScriptEngines”
Add the following 2 lines to the [Yengine] section:
   ScriptStackSize = 2048
   ScriptHeapSize = 1024
   UseSourceHashCode = true
In the [Groups] section, uncomment Enabled and set it to true
Uncomment Module = "Groups Module V2"
Uncomment StorageProvider = OpenSim.Data.MySQL.dll
Uncomment ServicesConnectorModule and change to "Groups HG Service Connector"
Uncomment LocalService and change to remote
Uncomment GroupsServerURI and change to "${Const|BaseURL}:${Const|PrivatePort}"
Uncomment HomeURI and set to "${Const|BaseURL}:${Const|PublicPort}"
Uncomment MessagingModule = "Groups Messaging Module V2"
Uncomment MessageOnlineUsersOnly and set to true
Or just replace the whole section with:
   Enabled = "true"
   Module = "Groups Module V2"
   StorageProvider = OpenSim.Data.MySQL.dll
   ServicesConnectorModule = "Groups HG Service Connector"
   LocalService = "remote"
   GroupsServerURI = "${Const|BaseURL}:${Const|PrivatePort}"
   HomeURI = "${Const|BaseURL}:${Const|PublicPort}"
   MessagingModule = "Groups Messaging Module V2"
   NoticesEnabled = true
   MessageOnlineUsersOnly = true
In the [NPC] section, uncomment AllowSenseAsAvatar and set to false
**********************end of the sections brought from OpenSim.ini****************
In the [Databaseservice] section comment out the SQLite Include line.
Uncomment StorageProvider = "OpenSim.Data.MySQL.dll"
Uncomment the ConnectionString and fill in your MySql user and password
Uncomment the gridname and change it to your grid name
In the [Hypergrid] section uncomment GatekeeperURI
In the [Modules] section, comment out the Include-FlotsamCache line
Add this new section below the [Modules] section
[AssetCache]
       CacheDirectory = "../ ../ ../ ../Data/assetcache"
       LogLevel = 0
       HitRateDisplay = 0              ;Hyacinth disabled this
       NegativeCacheEnabled = "true"
       NegativeCacheTimeout = 120
       NegativeCacheSliding = "false"
       MemoryCacheEnabled = "false"
       FileCacheEnabled = "true"
       FileCleanupTimer = 0.0          ;Hyacinth disabled this
       FileCacheTimeout = 48
In the [GridSevice] section, uncomment AllowHypergridMapSearch
Uncomment and change MapTileDirectory = "../ .. / ../ ../Data/maptiles
In the [EstateDataStore] section uncomment LocalServiceModule
In the [EstateService] section, uncomment EstateServerURI
At the very end of GridCommon.ini, add this new section:
[LocalInclude]
       Include-Local = "../Local.ini"  ;;include last to over-ride anything

Now this GridCommon.ini file really does match its name and all the regions use the one copy up there.

Editing the Local.ini File

You will create a new Local.ini file in the home directory of the region. The OpenSim.ini file normally has things that only apply to the local region that one copy of OpenSim is managing. I moved those things out into a Local.ini file that lives in the folder dedicated for each region so OpenSim.ini did not need editing for each region. For example in the ...Grid/Welcome folder. Here is an example Local.ini file:

;; Local.ini
;;  The settings which are unique for each region
[Const]
   RegionDir ="Welcome"		;what folder this region is in
[Network]
   http_listener_port = 8022
[Estates]
   DefaultEstateName = "Arcadia Asylum Asset Archive"
   DefaultEstateOwnerName = "Arcadia Asylum"

I use the constant RegionDir to construct paths to the directory Local.ini is stored in when I cannot use a relative path like “../ ..” Each region needs a unique http_listener_port, although if there is only one region in an instance it can use the same port number as the InternalPort in the Regions.ini file. (One is TCP the other UDP, so they do not conflict) Setting the DefaultEstateName and DefaultEstateOwnerName here is the easiest way to create new estates. The user name must already exist for this to work, so create them first.

If you need to set any parameters different for this region, you can set them here and they will over-write any settings in the rest of the INI files. That is because it is interpreted last. For example you could change physics engine, money, OSSL function enables, etc.

Editing the Regions.ini File

Each OpenSim instance typically runs just one region, so there will be one Regions.ini file with one region described in it. The Regions folder that comes with the OpenSim binaries has an example. Here is an example file for a Welcome region. Below I’ll discuss what you must change in this file:

[Welcome]
RegionUUID = 7bd33f64-3c02-4570-a464-0908d89fb850
Location = 1000,1000
InternalAddress = 0.0.0.0
InternalPort = 8020
AllowAlternatePorts = False
ExternalHostName = yourgrid.com
SizeX = 512
SizeY = 512
       ; * Default region landing point used when no teleport coords are specified
DefaultLanding = <128,128,30>
; * Prim data. This allows limiting the sizes of prims and the region prim count
       NonPhysicalPrimMax = 512
       PhysicalPrimMax = 150
       ClampPrimSize = False
       MaxPrims = 30000
       MaxAgents = 40

The first line of a Regions.ini file contains the name of the region. This can have spaces, apostrophes, underscores and lots of other characters that are a nightmare in file names. Linux allows many special characters in file names but this still creates lots of problems. For this reason in my grid management code I take the region name and convert spaces and apostrophes into dashes before using them as the folder names. So “Na’vi Home Tree” can be used in the Regions.ini file, but store everything for this region in a folder named “Na-vi-Home-Tree”. If there are other special characters you like in region names, let me know.

The RegionUUID MUST BE UNIQUE. You can get a unique UUID from https://www.uuidgenerator.net/ Once you have one unique UUID you can change it slightly for other regions. For example, I will take the welcome region Regions.ini file as a template for my next few regions and change some of the digits in it to the x and y location or the port number of the new region. The Location is the X and Y position on the map where the SW corner of your region starts. Var regions extend north and to the east (up and left). If var regions overlap, OpenSim may tell you, but you should be careful about placement.

The InternalPort number MUST BE UNIQUE although it is typically identical to the http_listener_port for the OpenSim instance which I store in the Local.ini file.

DefaultLanding is difficult, there are many ways to choose where avatars land. One way is the viewer often sends people to <128,128,21> so all the other ways to choose a landing sight are problematically

MaxPrims is not enforced in OpenSim but is recorded and can be enforced with helper scripts and might be enforced leter.

The Location is the X and Y position on the map where the SW corner of your region starts. Var regions extend north and to the east (up and left). If var regions overlap, OpenSim may tell you, but you should be careful about placement.

SizeX and SizeY must be multiples of 256 and currently the X and Y size must be equal. Very large regions take a long time to load, so keep this reasonable. I recommend having 4x4 regions or smaller.

MaxPrims is not enforced in OpenSim but it is traced by the server, can be monitored manually or by helper tasks and may be implemented in the future.

The New Order and Location that the INI files are read now

For the Welcome region:

Grid/Regions/Welcome/bin/OpenSimDefaults.ini
                         | addon-modules/*/config/*.ini
Grid/Regions/Welcome/bin/OpenSim.ini
 | Grid/osslDefaultEnable.ini
 |        | osslEnable.ini
 | Grid/GridHypergrid.ini
 |        | GridCommon.ini
 |             |../Local.ini
 Grid/Regions//Welcome/Regions/Regions.ini

Starting Your first OpenSim Region

You must have started Robust and it must still be running in a 'screen' or another terminal window. Like starting Robust, you will want to run each OpenSim instance in the background in a ‘screen’ but the first time, and perhaps every time you make changes to the INI files, you can run it in an SSH terminal window. The advantage of that is the display will be in color for seeing ANGRY RED ERROR MESSAGES and the SSH window may be able to scroll back farther to find those errors. So after editing the ini file, while I am still in the bin folder, the first (few) times I just run:

   mono OpenSim.exe

Then 'quit' out if it to edit the ini file again. Rinse and repeat. Once it is running with no errors run it in a screen:

   screen -S Welcome
   mono Welcome.exe

While OpenSim.exe is starting you will see many messages scrolling by. Big blocks of error messages must be investigating. One or two red lines can be ignored, the [Money] module displays red messages to tell you that is not enabled. When you start an opensim region, you will see it connecting in the Robust console. When an avatar logs onto your grid, you will see that logged in the region console. Once the region comes up, you can start using console commands, like help, load oar etc. In my configuration files I disable the default behavior of generate maps on every region start. So one command you should run is 'generate map' to make sure the region appears in the map. When you are done with setting up the region in a 'screen', do not forget to exit by typing ctrl-a ctrl-d to leave OpenSim.exe running in the background.

Next: Setting up and starting your second region which will be much easier