OpenSimulator · EN

FSAssets: complete technical guide

Architecture, asset storage, SQL metadata, compression, spool and ROBUST configuration.

Guide grounded in the OpenSimulator 0.9.3.1 / .NET 8 fork. Verify your version and back up before changing a live installation.

What FSAssets replaces — and what it does not

FSAssets stores asset payloads as files on disk and asset metadata in a database. It does not replace inventory databases, region databases or OAR/IAR archives. An inventory entry can therefore still point to an absent asset file.

Understand the write pipeline

The code hashes payload bytes with SHA-256. An asset is first written under SpoolDirectory/spool, moved into SpoolDirectory, then processed by a writer thread into a compressed .gz under BaseDirectory. SQL records map UUIDs to hashes. A consistent production backup must account for the live spool as well as final files.

Enable the connector in ROBUST

In [AssetService], exactly one LocalServiceModule setting must be active. Switch from the default asset service to FSAssets only with a backup and rollback plan. ROBUST reads the actual INI selected on startup; distinguish Robust.ini, Robust.HG.ini and their .example templates.

Adapt this example: never run blindly in production.

[AssetService]
LocalServiceModule = "OpenSim.Services.FSAssetService.dll:FSAssetConnector"
BaseDirectory = "/srv/opensim/fsassets/data"
SpoolDirectory = "/srv/opensim/fsassets/tmp"
DaysBetweenAccessTimeUpdates = 30
ShowConsoleStats = true
UseOsgridFormat = false

Prepare the directories

Create data and tmp on a mounted volume and verify that the ROBUST service account can read/write them. Avoid running ROBUST as root; use the real service identity. Absolute paths are easier to troubleshoot than relative paths.

Adapt this example: never run blindly in production.

# À adapter à votre compte de service et à votre montage
sudo install -d -o opensim -g opensim -m 750 /srv/opensim/fsassets/data
sudo install -d -o opensim -g opensim -m 750 /srv/opensim/fsassets/tmp
findmnt -T /srv/opensim/fsassets/data
findmnt -T /srv/opensim/fsassets/tmp
sudo -u opensim test -w /srv/opensim/fsassets/data && echo 'data writable'
sudo -u opensim test -w /srv/opensim/fsassets/tmp && echo 'tmp writable'

SpoolDirectory and BaseDirectory: same filesystem

The fork templates explicitly require BaseDirectory and SpoolDirectory on the same physical filesystem. Keep spool and final storage on one mounted filesystem. Do not rely on /tmp if it is on a separate disk or cleaned at boot. Check actual mounts, including symbolic links.

Adapt this example: never run blindly in production.

readlink -f /srv/opensim/fsassets/data
readlink -f /srv/opensim/fsassets/tmp
findmnt -T /srv/opensim/fsassets/data -o TARGET,SOURCE,FSTYPE,OPTIONS
findmnt -T /srv/opensim/fsassets/tmp -o TARGET,SOURCE,FSTYPE,OPTIONS

Understand configuration settings

FallbackService provides a source for missing assets and may support controlled migration from legacy storage. Realm selects the metadata table (fsassets by default). StorageProvider and ConnectionString fall back to [DatabaseService] when not set in [AssetService]. DaysBetweenAccessTimeUpdates reduces SQL access-time writes. ShowConsoleStats toggles stats. SecondaryInstance is for carefully designed multi-instance deployments.

Directory layout and UseOsgridFormat

The standard layout splits the hash prefix into 2, 2, 2 and 4-character directory components; UseOsgridFormat=true uses two 3-character levels. Switching this on an existing store changes the expected path and can make assets appear missing. Never toggle it without a verified file migration.

Hash, UUID and deduplication

Code uses a content hash for the file path and UUIDs for SQL metadata. Several UUIDs can refer to identical payload bytes, so metadata row count need not equal file count. The final filename is derived from the hash, not from the UUID.

Available console commands

The connector registers show assets, show digest <ID>, delete asset <ID>, import and force import. The first two are useful diagnostics; delete asset and force import mutate metadata or overwrite content: never run them just to test. These commands exist on the console loading FSAssets.

Adapt this example: never run blindly in production.

show assets
show digest 00000000-0000-0000-0000-000000000000

Relationship with Hypergrid

The fork also has HGFSAssetService. It is not an automatic substitute for FSAssetConnector: cross-grid transfers, permissions and identity handling have separate rules. Check the configured HG connector before changing services.

Checking that FSAssets works

The FS asset service enabled message indicates module startup but does not prove every asset is intact. Test writing a new asset, reading after restart, spool health and retrieval in a viewer. One texture is not an exhaustive integrity check.

Further reading

Source code and documentation