FSAssets: migration, import and relocation
Migrate from MySQL, relocate to another volume and protect SQL/file consistency.
Before migration: inventory and rollback
Record exact version, active INIs, current asset backend, source SQL database, asset count, disk and inode capacity. Make a consistent database dump, a reliable file backup and test on a staging instance. Do not improvise on the only production copy.
Migration from legacy assets table
The module exposes import and force import console commands; FallbackService can also retrieve missing assets on demand. These approaches are not interchangeable and require staging tests. Import takes a connection string and table, optionally start/count; a wrong source or table can import incorrect data.
Adapt this example: never run blindly in production.
# Syntaxe de référence du connecteur FSAssets (ne pas exécuter en aveugle) import <connection-string> <legacy-table> [<start> <count>] # DANGEREUX : force import peut écraser le contenu existant force import <connection-string> <legacy-table> [<start> <count>]
Be careful with SQL credentials in commands
A password in console commands can leak into history, logs or screenshots. Use a least-privilege migration account and secure handling. Never paste the connection string into a public ticket.
FallbackService and lazy migration
When FSAssets metadata or file is missing, code can query FallbackService and store returned content. This is on-demand migration, not proof that all old assets were moved: rarely used assets can remain only in the legacy service. Do not retire the old backend without comprehensive verification.
Relocate the store to a new disk
Recommended sequence: full backup, prepare new filesystem, check inodes, initial copy, controlled stop of the writer service, final copy including spool, validate permissions/mounts, edit the active INI, restart and test. Do not only move BaseDirectory while leaving SpoolDirectory on the old volume.
Rsync pre-copy
Copy both trees preserving permissions, timestamps and symlinks. The initial rsync can run online but is not a consistent backup: files may change during the copy. Do not add --delete until source, destination and recovery plan are validated.
Adapt this example: never run blindly in production.
# EXEMPLES : chemins fictifs, sans --delete sudo rsync -aHAX --numeric-ids --info=progress2 /ancien/fsassets/data/ /nouveau/fsassets/data/ sudo rsync -aHAX --numeric-ids --info=progress2 /ancien/fsassets/tmp/ /nouveau/fsassets/tmp/ # Répéter après arrêt contrôlé de ROBUST pour finaliser
Progressive pre-copy, dry-run and final cutover
During the initial copy, nice -n 19 ionice -c2 -n7 can reduce contention. Use screen to survive SSH disconnects and rsync --dry-run to preview differences. After all FSAssets writers stop, a final sync reconciles files. Downtime depends on remaining differences and is not guaranteed; never cut over without mount, spool and SQL-metadata checks.
Example paths only: adapt both directories and the SQL/spool strategy.
nice -n 19 ionice -c2 -n7 rsync -a --info=progress2 /srv/opensim/fsassets/ /mnt/newdisk/fsassets/ rsync -a --dry-run --itemize-changes /srv/opensim/fsassets/ /mnt/newdisk/fsassets/ # Après arrêt contrôlé de tous les écrivains : rsync -a --info=progress2 /srv/opensim/fsassets/ /mnt/newdisk/fsassets/
Use --delete only after verifying paths and previewing its effects with --dry-run; it is not required for every migration and never replaces a separate backup. Retain the old directory through validation instead of deleting it immediately.
Persistent mounts and symlinks
Prefer a persistent UUID-based /etc/fstab mount and check findmnt before starting. A symlink can preserve an old path, but it does not protect against missing mounts: the service could write into an empty root-disk directory. A systemd unit may use RequiresMountsFor to guard against this.
Adapt this example: never run blindly in production.
lsblk -f findmnt -T /nouveau/fsassets/data readlink -f /nouveau/fsassets/data # Vérifier les permissions sous l'identité réelle du service
Post-cutover validation
Check Robust.log for [FSASSETS] errors, expected mount, inode capacity, show assets and show digest for a known UUID, then textures and objects in a viewer. Also test a newly uploaded asset and its retrieval after restart. Keep the original storage read-only until validated.
Adapt this example: never run blindly in production.
findmnt -T /nouveau/fsassets/data df -h /nouveau/fsassets/data df -i /nouveau/fsassets/data grep -nEi '\[FSASSETS\]|IOException|No space left' /chemin/vers/Robust.log | tail -n 100
Do not change UseOsgridFormat during relocation
File paths are derived from hashes. Keeping the same format across relocation preserves layout. Switching false to true (or vice versa) without moving every file to its expected new path makes assets invisible. Treat layout changes as a separate conversion requiring a verified tool and backups.
Avoid partial cutovers
Restoring FSAssets SQL metadata without matching payloads creates broken references; restoring files without matching metadata prevents UUID lookup. Back up and restore a consistent set: SQL + data + spool + configuration + application version.