Revision as of 14:19, 22 April 2011

Structure

OpenSimulator has a fairly complicated configuration structure based on Windows style INI files. This is to accomodate its many different uses and possible architectures.

Configuration files can include other configuration files. For instance, a standard standalone configuration will read the following INI files (you can see this order early on in the log and on the console).

OpenSimDefaults.ini (OpenSim 0.7.1-rc1 and onwards)
OpenSim.ini
config-include/Standalone.ini
config-include/StandaloneCommon.ini
config-include/CenomeCache.ini (not found on a default setup)
config-include/storage/SQLiteStandalone.ini

OpenSimDefaults.ini (on OpenSim 0.7.1-rc1 and later) and OpenSim.ini are always checked for on startup. However, the other INI files are loaded as a result of include directives within the preceding INI files.

For instance, at the bottom of the OpenSim.ini file in the [Architecture] section, there are a number of possible architectural includes. For example, a default OpenSim 0.7.1-rc1 standalone setup will have

[Architecture]
   Include-Architecture = "config-include/Standalone.ini"
   ; Include-Architecture = "config-include/StandaloneHypergrid.ini"
   ; Include-Architecture = "config-include/Grid.ini"
   ; Include-Architecture = "config-include/GridHypergrid.ini"
   ; Include-Architecture = "config-include/SimianGrid.ini"
   ; Include-Architecture = "config-include/HyperSimianGrid.ini"

Lines that start with at least one semicolon (;) are commented out and are not active in the configuration. In this case, when OpenSimulator reads OpenSim.ini it will then go on to read config-include/Standalone.ini, which in turn includes config-include/StandaloneCommon.ini and so on.

If a config file isn't found then it is ignored and it's non-existence is logged.

Changing Simulator Settings

A configuration file consists of a number of sections, each starting with the name of that section in brackets ([]). For instance, in OpenSim.ini.example you have (ignore the descriptive text)

[Startup]
   ; save_crashes = false
   ; crash_dir = "crashes"
   ...

[SMTP]
   ; enabled = false
   ...

[Chat]
   ; whisper_distance = 10

The config parameters follow each section. Each has the structure <parameter> = <value> (e.g. whisper_distance = 10).

In OpenSim.ini.example, if a parameter is commented out with a preceding semicolon (;), then the value in OpenSimDefaults.ini is used instead (in OpenSim 0.7.1-rc1 and later) or a default value within OpenSim itself.

To change a parameter, one would uncomment it and edit the value. For instance, if I wanted whisper distance to be 50 meters in my sim, I would change OpenSim.ini so that it had.

[Chat]
   whisper_distance = 50

When the sim was next started up, the whisper distance would be 50m, overriding any value in OpenSimDefaults.ini if it exists.

In OpenSim 0.7.1-rc1 and later, we recommend that parameters are changed in OpenSim.ini and not in OpenSimDefaults.ini. This is because various parameters are added or can change name between releases. Common parameters to change are already in OpenSim.ini.example - OpenSimDefaults.ini contains both defaults for these parameters and more obscure ones. If you want override a parameter that is in OpenSimDefaults.ini but not OpenSim.ini.example then we recommend that you copy the relevant section to OpenSim.ini and change it there.

Aggregation and Overriding

As we saw above, when multiple config files have the same section, the settings are aggregated. If a later setting has the same name as an earlier setting, then the later setting overrides the earlier setting.

Getting information about parameters

On the simulator's console command line, you can get information about what parameters it's actually using with the "config show" command. This is handy if you want to check that the simulator has loaded the parameters that you want.