Configuring Simulator Parameters
From OpenSimulator
Contents |
Structure
Please note that the cascading configuration file system described below does not apply to Robust instances at this time.
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 (OpenSimulator 0.7.1 and onwards) OpenSim.ini config-include/Standalone.ini config-include/StandaloneCommon.ini config-include/FlotsamCache.ini config-include/storage/SQLiteStandalone.ini
OpenSimDefaults.ini (on OpenSimulator 0.7.1 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 OpenSimulator (since 0.7.1) 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"
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.
The OpenSim.ini and OpenSimDefaults.ini files in bin/ concern simulator parameters (chat distance, physics, etc.). The parameters in config-include control the location and parameters of data services (e.g. region database, asset service, inventory service).
Changing Simulator Settings
Do not forget to copy OpenSim.ini.example to OpenSim.ini on install
- Do not change OpenSimDefaults.ini. Only edit OpenSim.ini. If necessary, copy the lines from it, into same section on OpenSim.ini (add the section if not there), and then change there.
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, if a parameter is commented out with a preceding semicolon (;), then the value in OpenSimDefaults.ini is used instead (in OpenSimulator 0.7.1 and later) or a default value within OpenSimulator code 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 OpenSimulator 0.7.1 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.
You cannot have multiple sections with the same name (e.g. [DatabaseService]) in the same file (e.g. bin/config-include/GridCommon.ini). The second section will completely replace the first. To merge sections with the same name they must be situated in different .ini files.
Getting information about parameters
On the simulator's console command line, you can get information about what parameters it's actually using from the all the .ini files with the "config show" command. This is handy if you want to check that the simulator has loaded the parameters that you want. The "config save <path>" command will save this aggregated config.
Using Key Expansion to simplify configuration
We use the same information in many places throughout the files that configure our servers. To help simplify the configuration process, we leverage "Key Expansion". With Key Expansion we are able to define these values in one place to be used anywhere in the set of configuration files. The configuration system uses the common syntax for parameter expansion: ${VARIABLE}. But, our configuration files have many sections, so our syntax adds the ability to address keys within the various sections of the set of configuration files using the pipe "|" to separate the two. Then, our syntax becomes: ${SECTION|KEY}. In the set of example configuration files distributed with OpenSimulator, we are using this feature to ease the definition of ports and urls in the file set, as these keys are used in many places. We set them in a newly added section ...
[Const] BaseURL = http://127.0.0.1 PublicPort = 8002 PrivatePort = 8003
Then we are able to use them in the many places they are needed by using our Key Expansion Syntax instead of the Key = Value seen elsewhere...
[Startup] HomeURI = ${Const|BaseURL}:${Const|PublicPort}
And when OpenSimulator starts and reads the set of configuration files, the end-result will be ...
[Startup] HomeURL = http://127.0.0.1:8002
And while it may not be quite so useful in our case, we may use the syntax to use keys defined in the same sections by omitting the section and pipe - ${KEY}.
Using shell environment variables in OpenSimulator configuration
We will need to use two new things in our configurations: a section [Environment] to tell us what variables we need to look at in the shell and we will need to use the Nini key expansion. Nini, can have keys that look like ${SECTION|VARIABLE} and can expand those to the variables we assign.
In your shell you will export your values and check the ones you want to use that are predefined by your system ...
export RT_ZONE=Zone_00
# You can see your HOSTNAME (It will be set by the system)... echo $HOSTNAME OSERV_00
In the ini you will include an [Environment] section...
[Environment] ; Our Environment section that defines the shell variables we are interested in RT_ZONE="" ; We might use a zone to setup an instance of OpenSimulator on a server HOSTNAME="" ; We might be interested in obtaining the host's name [Startup] regionload_regionsdir=/home/opensim/etc/Regions/${Environment|RT_ZONE}/ ; We set our regionload_regionsdir using the variables ConsolePrompt = "${Environment|HOSTNAME}:${Environment|RT_ZONE} " [DatabaseService] ConnectionString = "Data Source=localhost;Database=${Environment|RT_ZONE};User ID=username;Password=userpass;" ; Here too
When OpenSimulator picks up the variables in your shell and processes all the configurations, the variable keys will be filled in with the variables picked up from the shell ...
[Environment] ; Our Environment section that defines the shell variables we are interested in RT_ZONE="" ; We might use a zone to setup an instance of OpenSimulator on a server HOSTNAME="" ; We might be interested in obtaining the host's name [Startup] regionload_regionsdir=/home/opensim/etc/Regions/Zone_00/ ; We set our regionload_regionsdir using the variables ConsolePrompt = "OSERV_00:Zone_09 " [DatabaseService] ConnectionString = "Data Source=localhost;Database=Zone_00;User ID=username;Password=userpass;" ; Here too
