FSAssets: complete technical guide
Architecture, asset storage, SQL metadata, compression, spool and ROBUST configuration.
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
- FSAssets : inodes, disques et performances
- FSAssets : migration et déplacement
- FSAssets : sauvegarde et restauration
- FSAssets : dépannage par les logs