Configuration reference

← Back to docs · Quick start · Architecture

Welkin reads TOML configuration files at startup. Each binary takes a --config flag pointing to its config file; defaults are welkin.toml for the region simulator and robust.toml for grid services.

File format

Standard TOML. Top-level tables become config sections; keys inside them are typed as string, integer, boolean, or float.

Welkin checks the type of boolean, integer and float settings. A value of the wrong type, such as PhysicsEnabled = "false" (a string) where a boolean is expected, is logged as an error naming the section, key and value, and Welkin uses the setting's default instead. Watch the startup log after editing a config file. An integer is accepted wherever a float is expected, so Gain = 10 works for a float setting.

[Region]
RegionName = "My Region"
RegionLocX = 1000
RegionLocY = 1000

[Scene]
PhysicsEnabled = true
ScriptsEnabled = true

Values from one section can reference another with ${Section|Key} substitutions. The config loader resolves these iteratively (up to 10 passes), so forward references work.

[Network]
ExternalHostName = "grid.example.com"

[GridService]
GridServerURI = "http://${Network|ExternalHostName}:8003"

Environment overrides

Any config value can be overridden by an environment variable prefixed with OPENSIM__, using double underscores to separate section and key:

export OPENSIM__Region__RegionName="Production Region"
export OPENSIM__Network__InternalPort=9010

Values are auto-typed: true/false become booleans, numeric strings become integers or floats, everything else is a string. Environment overrides apply after the config file loads and before substitution resolution, so they participate in ${Section|Key} expansion.

OpenSimulator INI import

The welkin-config crate can read C# OpenSimulator .ini files via import_ini(). This lets the migration tool (welkin-migration) convert an existing OpenSim.ini or Robust.ini to TOML without manual rewriting. Keys are lowercased during import (matching the configparser crate's behavior).

welkin-region (region simulator)

CLI: welkin-region --config <path> [--region-config <path>]

Defaults: --config welkin.toml. The optional --region-config flag loads a second file that merges on top, for per-region overrides in multi-region setups.

SectionKeyTypeDefaultPurpose
RegionRegionNamestringMy RegionDisplay name shown to viewers
RegionRegionLocXint1000Grid X coordinate
RegionRegionLocYint1000Grid Y coordinate
RegionRegionUUIDstring(generated once)Fixed UUID for the region; see below
NetworkExternalHostNamestring127.0.0.1Public hostname or IP that viewers connect to
NetworkInternalPortint9000UDP port for LLUDP viewer traffic
DatabaseServiceRegionConnectionStringstringsqlite:region.dbDatabase URL for region object storage
DatabaseServiceRobustConnectionStringstringsqlite:robust.dbDatabase URL for grid service queries
GridServiceGridServerURIstring(none)URL of the ROBUST grid service private port
ScenePhysicsEnabledbooltrueRun Rapier physics simulation
SceneScriptsEnabledbooltrueRun LSL/OSSL script execution
EstateEstateOwnerstring(none)Avatar UUID of the estate owner. Only the owner and managers may terraform or use estate tools
EstateEstateManagersstring(none)Comma-separated avatar UUIDs with estate manager rights
Permissionsserverside_object_permissionsbooltrueSet false to switch all permission checks off (development only)
Permissionsregion_owner_is_godbooltrueTreat the estate owner as an administrator

Permission checks are on by default. Without EstateOwner nobody has estate rights; avatars can still edit, move and delete objects they own. The region logs a warning at start-up when no owner is configured, and an error for any EstateOwner or EstateManagers entry that is not a UUID.

The region also stores its estate in the region database (the estate_settings, estate_map and estate_managers tables). On the first start it creates the estate with OpenSimulator's defaults and writes the configured owner and managers into it. Later starts read the stored estate, so you can drop the [Estate] section after the first start. A different EstateOwner in the config replaces the stored owner. The region runs its database migrations at every start, so the tables for objects, terrain and the estate exist on a fresh database.

Everything the region saves (objects, terrain, estate link, settings) is keyed by the region's UUID. If you leave RegionUUID out, the region generates one on its first start and stores it in the region database under its name and location, then reuses it on every later start. Set RegionUUID when you need a known value, for example when you move a region to a new database or machine and want it to find its saved data. The setting must be a valid UUID, or the region refuses to start. If you rename a region or change its location without setting RegionUUID, the region generates a new UUID and no longer sees its earlier data.

welkin-robust (grid services)

CLI: welkin-robust --config <path> [--public-port <port>] [--private-port <port>]

Defaults: --config robust.toml, --public-port 8002, --private-port 8003. The private port binds to 127.0.0.1 by default, because it serves account and authentication endpoints without authentication. To bind another address, pass --private-bind <address> or set WELKIN_PRIVATE_BIND. The container image sets WELKIN_PRIVATE_BIND=0.0.0.0 so other containers can reach it; keep the published port off the public network. A region on a different host cannot reach the private port until you change the bind address. The public port handles viewer login (XMLRPC) and user-facing caps. The private port handles inter-service traffic (grid registration, asset storage, inventory queries).

SectionKeyTypeDefaultPurpose
DatabaseServiceConnectionStringstringsqlite:robust.dbDatabase URL for all grid services
DatabaseServiceRobustConnectionStringstring(from ConnectionString)Override when grid services need a separate database
UserAccountServiceAllowCreateUserboolfalseLet the createuser grid method create accounts
AssetServiceAssetLoaderEnabledbooltrueLoad the default asset sets at start
AssetServiceAssetLoaderArgsstringassets/AssetSets.xmlPath to the asset set control file

At start welkin-robust loads OpenSimulator's default asset sets (the default avatar body parts, clothing, animations and sounds) into the asset store, so viewers can fetch them. Without them avatars appear untextured. AssetLoaderArgs names a control file in OpenSimulator's AssetSets.xml format; each section in it points to a set file that lists the assets. The loader adds every asset that is not already in the store, so it is safe to run on every start.

This repository does not include AssetSets.xml or the set files, because the assets are Linden Lab viewer art under CC BY-SA 2.5. Copy the bin/assets folder from an OpenSimulator 0.9.3.0 installation to assets/ in the directory you start welkin-robust from, or point AssetLoaderArgs at your copy. See the quick start. If the control file is missing, the grid logs a warning (AssetSets.xml not found; default avatar assets are not seeded) and starts anyway. Set AssetLoaderEnabled = false to skip the loader.

AllowCreateUser matches OpenSimulator's default. While it is false, the create-user console command in welkin-region fails with "grid refused to create the user". Set it to true only on a development or test grid, or briefly while you create the first account. When it is true, anyone who can reach the private service port (8003 by default) can create accounts, so keep that port off the public network.

[UserAccountService]
AllowCreateUser = true

Database URLs

All database URLs use the same format across both binaries:

BackendURL formatNotes
SQLitesqlite:path.db?mode=rwc?mode=rwc creates the file if absent
MariaDB/MySQLmysql://user:pass@host/dbVia sqlx with the MySQL driver
PostgreSQLpostgres://user:pass@host/dbVia sqlx with the Postgres driver

The migration runner and the region's identity and saved-script storage use the placeholder style of the backend in use ($1 for PostgreSQL, ? for SQLite and MariaDB), and the key columns of the region identity and saved-script tables are VARCHAR so they work on MariaDB.

SQLite is the only backend that has been run and verified. The code supports MariaDB and PostgreSQL, but no one has run the region or grid services against either of them yet, and these problems are known:

  • The welkin-data crate still has about 158 hardcoded $n placeholders, which work on PostgreSQL and SQLite but not on MariaDB. A sweep to make them backend-aware is pending.
  • The script_states table stores scripts in a BLOB column, which needs BYTEA on PostgreSQL and LONGBLOB on MariaDB.
  • The loc_x and loc_y columns of the region identity table need BIGINT on PostgreSQL (issue #79).

Use SQLite until these are fixed. The MariaDB and PostgreSQL instructions in the operator guide describe the intended setup, not a verified one.

Logging

The region simulator reads a [Logging] section at startup. Welkin does not read OpenSimulator's log4net XML file, so the logconfig key under [Startup] has no effect. Every key below is optional.

KeyTypeDefaultPurpose
DirectorystringlogsFolder for log files; created if absent
FilePrefixstringregion.logStart of each log file name; the rotation date is appended
Rotationstringdailyhourly, daily, or never; any other value means daily
MaxFilesint14Rotated files to keep; 0 keeps all of them
LevelstringinfoBase level: error, warn, info, debug, or trace
Filterstring(empty)Extra per-module directives, appended to Level
JsonboolfalseWrite JSON lines instead of plain text, to the console and the file
ConsolebooltrueWrite logs to standard error
FilebooltrueWrite logs to rotating files

Filter takes comma-separated target=level pairs. With Level = "info" and Filter = "welkin_net=debug,welkin_scene=warn", Welkin logs at info level, with debug output from the network crate and only warnings from the scene crate.

[Logging]
Directory = "logs"
Rotation = "hourly"
MaxFiles = 48
Level = "info"
Filter = "welkin_net=debug"

If the RUST_LOG environment variable is set, it replaces both Level and Filter. An invalid RUST_LOG or Filter value falls back to info. MaxFiles and Rotation apply only when File is true. File output goes through a background writer, so lines written just before a crash can be lost.

Admin API

The region simulator can expose a small REST API for console commands. It stays off until you set a token.

SectionKeyTypeDefaultPurpose
AdminTokenstring(empty)Bearer token; an empty value disables the API
AdminBindAddressstring127.0.0.1Interface the API listens on
AdminPortint9100TCP port for the API
AdminAllowRemoteBindboolfalsePermit BindAddress to be a non-loopback address
[Admin]
Token = "a-long-random-string"
BindAddress = "127.0.0.1"
Port = 9100

Clients call POST /admin/console with the header Authorization: Bearer <token>.

[!WARNING] The admin API uses plain HTTP, with no TLS. The token and every command, including passwords typed into create-user, travel in cleartext. For that reason the region refuses to start the API on a non-loopback BindAddress and logs an error, unless you also set AllowRemoteBind = true. Keep BindAddress at 127.0.0.1, or put the API behind a reverse proxy that terminates TLS. See the operator guide.

Backup

The region simulator saves changed objects to the database on a timer.

KeyTypeDefaultPurpose
IntervalSecondsint900Seconds between saves; values below 5 are raised to 5, and values of 0 or less use the default
[Backup]
IntervalSeconds = 300

Each save writes only objects that changed since the last one, and logs the count at info level when it is above zero. The same timer saves the terrain if it was edited since the last save. Terrain is stored in OpenSimulator's database format (revision 23, a gzip of the height field with heights rounded to 3 decimals), and the region loads it at start. A terrain edit made after the last save is lost if the region stops before the next one. At start the region loads its saved objects, terrain and estate. Objects created since the last save count as unsaved and go out on the next one.

OpenSimulator saves on a frame count instead: the scene writes to storage every UpdateStorageEveryNFrames frames, 200 by default. Welkin uses wall-clock time on purpose, so the save interval does not shift with the frame rate. If you are migrating, set IntervalSeconds for the delay you want and drop UpdateStorageEveryNFrames; Welkin ignores that key.

Groups

Group support in the region simulator is off by default, as in OpenSimulator.

SectionKeyTypeDefaultPurpose
GroupsEnabledboolfalseTurn on group data and group requests
GroupsGroupsServerURIstring(none)URL of the grid groups service
GroupsServiceServerURIstring(none)Second choice for the groups service URL

The region uses the first non-empty URL from [Groups] GroupsServerURI, then [GroupsService] ServerURI, then [GridService] GridServerURI, so a region that already points at welkin-robust needs only Enabled = true. The names match OpenSimulator's config.

[Groups]
Enabled = true

If Enabled is true but no URL is found, groups stay off. welkin-robust serves the groups service at /groups. See Viewer compatibility for what works.

Module configuration

Region modules read their settings through the ModuleConfig trait, which wraps the same section/key lookup with typed defaults:

  • get_string(section, key, default) -> String
  • get_int(section, key, default) -> i64
  • get_bool(section, key, default) -> bool
  • get_float(section, key, default) -> f64

Each module documents its own config section. Some examples:

[AssetCache]
MemoryCacheEnabled = true
MemoryCacheMaxItems = 30000
MemoryCacheTTL = 120
FileCacheEnabled = true
CacheDirectory = "assetcache"

[Network]
IPBanList = "1.2.3.4, 10.0.0."

[LandService]
ServiceURL = "http://127.0.0.1:8003"
Timeout = 25000

Network entries ending with a dot (like 10.0.0.) are treated as subnet prefixes by the IP ban module.

Config merge order

When multiple sources provide the same key, later sources win:

  1. Base config file (--config)
  2. Region config file (--region-config, region binary only)
  3. Environment variables (OPENSIM__*)
  4. Substitution resolution (${Section|Key})