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.
| Section | Key | Type | Default | Purpose |
|---|---|---|---|---|
| Region | RegionName | string | My Region | Display name shown to viewers |
| Region | RegionLocX | int | 1000 | Grid X coordinate |
| Region | RegionLocY | int | 1000 | Grid Y coordinate |
| Region | RegionUUID | string | (generated once) | Fixed UUID for the region; see below |
| Network | ExternalHostName | string | 127.0.0.1 | Public hostname or IP that viewers connect to |
| Network | InternalPort | int | 9000 | UDP port for LLUDP viewer traffic |
| DatabaseService | RegionConnectionString | string | sqlite:region.db | Database URL for region object storage |
| DatabaseService | RobustConnectionString | string | sqlite:robust.db | Database URL for grid service queries |
| GridService | GridServerURI | string | (none) | URL of the ROBUST grid service private port |
| Scene | PhysicsEnabled | bool | true | Run Rapier physics simulation |
| Scene | ScriptsEnabled | bool | true | Run LSL/OSSL script execution |
| Estate | EstateOwner | string | (none) | Avatar UUID of the estate owner. Only the owner and managers may terraform or use estate tools |
| Estate | EstateManagers | string | (none) | Comma-separated avatar UUIDs with estate manager rights |
| Permissions | serverside_object_permissions | bool | true | Set false to switch all permission checks off (development only) |
| Permissions | region_owner_is_god | bool | true | Treat 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).
| Section | Key | Type | Default | Purpose |
|---|---|---|---|---|
| DatabaseService | ConnectionString | string | sqlite:robust.db | Database URL for all grid services |
| DatabaseService | RobustConnectionString | string | (from ConnectionString) | Override when grid services need a separate database |
| UserAccountService | AllowCreateUser | bool | false | Let the createuser grid method create accounts |
| AssetService | AssetLoaderEnabled | bool | true | Load the default asset sets at start |
| AssetService | AssetLoaderArgs | string | assets/AssetSets.xml | Path 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:
| Backend | URL format | Notes |
|---|---|---|
| SQLite | sqlite:path.db?mode=rwc | ?mode=rwc creates the file if absent |
| MariaDB/MySQL | mysql://user:pass@host/db | Via sqlx with the MySQL driver |
| PostgreSQL | postgres://user:pass@host/db | Via 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-datacrate still has about 158 hardcoded$nplaceholders, which work on PostgreSQL and SQLite but not on MariaDB. A sweep to make them backend-aware is pending. - The
script_statestable stores scripts in aBLOBcolumn, which needsBYTEAon PostgreSQL andLONGBLOBon MariaDB. - The
loc_xandloc_ycolumns of the region identity table needBIGINTon 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.
| Key | Type | Default | Purpose |
|---|---|---|---|
| Directory | string | logs | Folder for log files; created if absent |
| FilePrefix | string | region.log | Start of each log file name; the rotation date is appended |
| Rotation | string | daily | hourly, daily, or never; any other value means daily |
| MaxFiles | int | 14 | Rotated files to keep; 0 keeps all of them |
| Level | string | info | Base level: error, warn, info, debug, or trace |
| Filter | string | (empty) | Extra per-module directives, appended to Level |
| Json | bool | false | Write JSON lines instead of plain text, to the console and the file |
| Console | bool | true | Write logs to standard error |
| File | bool | true | Write 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.
| Section | Key | Type | Default | Purpose |
|---|---|---|---|---|
| Admin | Token | string | (empty) | Bearer token; an empty value disables the API |
| Admin | BindAddress | string | 127.0.0.1 | Interface the API listens on |
| Admin | Port | int | 9100 | TCP port for the API |
| Admin | AllowRemoteBind | bool | false | Permit 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-loopbackBindAddressand logs an error, unless you also setAllowRemoteBind = true. KeepBindAddressat127.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.
| Key | Type | Default | Purpose |
|---|---|---|---|
| IntervalSeconds | int | 900 | Seconds 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.
| Section | Key | Type | Default | Purpose |
|---|---|---|---|---|
| Groups | Enabled | bool | false | Turn on group data and group requests |
| Groups | GroupsServerURI | string | (none) | URL of the grid groups service |
| GroupsService | ServerURI | string | (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) -> Stringget_int(section, key, default) -> i64get_bool(section, key, default) -> boolget_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:
- Base config file (
--config) - Region config file (
--region-config, region binary only) - Environment variables (
OPENSIM__*) - Substitution resolution (
${Section|Key})