OpenSimulator · EN

Display Names: installation, architecture and troubleshooting

Complete guide to Firestorm-compatible Display Names for OpenSimulator 0.9.3.x.

Third-party community module: verify build compatibility and endpoint security before exposing it publicly. This guide complements the source repository and its up-to-date installation documentation.

Download the Display Names module

Official precompiled ZIP for OpenSimulator 0.9.3.1, release v1.0.0. For another revision, compile the addon against the matching server source.

Download ZIP — OpenSimulator 0.9.3.1

View official release · Browse precompiled files · Module source code

The PHP/MySQL backend is separate: also obtain the source repository for web/displayname/ and database/displaynames.sql, then follow the full installation guide.

Purpose and compatibility

Display Names is an unofficial community module enabling Firestorm-compatible display names on OpenSimulator 0.9.3.x. A precompiled DLL is validated for 0.9.3.1; for other revisions, compile against the exact server source tree. Display names do not replace login usernames.

Architecture: shared backend and per-simulator module

The system uses a grid-wide HTTPS PHP/MySQL backend and a module on every simulator that needs Display Names CAPS. Updates can be broadcast to nearby viewers. Remote Hypergrid UUIDs unknown locally should fall back to legacy name handling rather than being fabricated as local accounts.

Prerequisites and supplied files

Prepare HTTPS, PHP with PDO MySQL, a MySQL database and backend read access to ROBUST UserAccounts. The 0.9.3.1 precompiled package includes the DLL, PDB and Mono.Addins manifest. Back up older versions and stop the simulator before replacing binaries.

Adapt the example: do not reuse paths or credentials without verification.

precompiled/OpenSimulator-0.9.3.1/DisplayNameSimModule.dll
precompiled/OpenSimulator-0.9.3.1/DisplayNameSimModule.pdb
precompiled/OpenSimulator-0.9.3.1/DisplayNameSimModule.addin.xml
# À copier dans bin/ du simulateur concerné

Create the Display Names database

Create a dedicated database and import the module repository's database/displaynames.sql into it. The schema creates display_names (name and next permitted change) and display_name_history (set/reset audit history). Do not confuse this database with ROBUST.

Adapt the example: do not reuse paths or credentials without verification.

CREATE DATABASE opensim_displaynames CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
-- Ensuite importer database/displaynames.sql dans cette base.

Required SQL privileges

The installation guide requires SELECT on robust.UserAccounts to resolve legacy names, and SELECT/INSERT/UPDATE/DELETE on the Display Names database. Adapt database names, allowed MySQL client hostname and secret. Avoid root and never expose MySQL to the public Internet.

Adapt the example: do not reuse paths or credentials without verification.

CREATE USER 'displaynames_user'@'localhost' IDENTIFIED BY 'SECRET_A_CHANGER';
GRANT SELECT ON `robust`.`UserAccounts` TO 'displaynames_user'@'localhost';
GRANT SELECT, INSERT, UPDATE, DELETE ON `opensim_displaynames`.* TO 'displaynames_user'@'localhost';

Install and configure the PHP service

Copy web/displayname/ from the module repository to an HTTPS-served directory. Copy config/config.php.example to config/config.php, then set db_host, db_port, db_user, db_pass, db_displaynames and db_robust. Never commit real config.php or allow web access to credentials/logs. ServiceBase points to the service directory, not /get.

Adapt the example: do not reuse paths or credentials without verification.

'db_host' => '127.0.0.1',
'db_port' => 3306,
'db_user' => 'displaynames_user',
'db_pass' => 'SECRET_A_CHANGER',
'db_displaynames' => 'opensim_displaynames',
'db_robust' => 'robust',
'change_delay_days' => 7,

Security warning for /set and /reset

The repository example uses allow_all_ips=true for remote simulators. In the current backend this allows write requests without IP restrictions; it is NOT authentication. A publicly exposed installation could allow unauthorized name changes through its endpoints. Add robust backend authentication and/or appropriately enforced network controls before opening to untrusted traffic; setting the option false may block all writes rather than provide an allowlist.

Test endpoints before enabling the module

Test GET /get with a local UUID on the final HTTPS URL; it should return JSON. Expected routes are GET /get, POST /set and POST /reset. For 404 check .htaccess, mod_rewrite/AllowOverride and directory location. Avoid HTTP 301/302 redirects for POST requests.

Adapt the example: do not reuse paths or credentials without verification.

curl -i 'https://grid.example/displayname/get?id=UUID_LOCAL'

Configure [DisplayNameCaps] in OpenSim.ini

Add this block as a separate section in the active OpenSim.ini. ServiceBase must not include /get, /set, /reset or /index.php. Other parameters control HTTP timeout, cache TTL, maximum concurrent calls and verbose logging.

Adapt the example: do not reuse paths or credentials without verification.

[DisplayNameCaps]
ServiceBase = "https://grid.example/displayname"
HttpTimeoutMs = 5000
CacheTtlMinutes = 30
MaxConcurrentServiceCalls = 5
Verbose = true

Enable the module in [Modules]

In the active GridCommon.ini, locate its existing [Modules] section and add DisplayNameCapsModule to SharedRegionModules. Preserve all existing shared modules and do not duplicate the SharedRegionModules setting. Actual include files depend on the deployment.

Adapt the example: do not reuse paths or credentials without verification.

[Modules]
SharedRegionModules = "DisplayNameCapsModule"
# Exemple si aucune autre valeur n’existe déjà.

Build for a different OpenSimulator revision

For an OpenSimulator 0.9.3.x revision different from the precompiled build, copy source/DisplayNameSimModule into addon-modules/DisplayNameSimModule of the matching OpenSimulator source tree, run prebuild and compile the Release solution. Verify generated DLL and addin manifest. This module runs in region simulators, not in ROBUST.

Adapt the example: do not reuse paths or credentials without verification.

# Linux (à la racine du code source OpenSimulator) :
./runprebuild.sh
dotnet build OpenSim.sln --configuration Release
# Windows : runprebuild.bat puis dotnet build OpenSim.sln --configuration Release

Verify module loading and initial Firestorm login

After restart search OpenSim.log for Plugin Loaded: DisplayNameSimModule and [DisplayNameCaps]: MODULE LOADED; the shared module should load once, not twice. If Mono.Addins fails discovery, stop the simulator and back up/rename addin-db-004 only when present. An initial Firestorm cache clear and complete viewer restart may be needed after first enabling Display Names.

Adapt the example: do not reuse paths or credentials without verification.

grep -nEi 'DisplayNameCaps|DisplayNameSimModule|ERROR|exception' /chemin/vers/OpenSim.log | tail -n 100

Test end-to-end behavior

Test: name above avatar and in profile, availability of legacy username, change, reset, updates observed by a second viewer, then Hypergrid contact behavior. Repeat on each enabled simulator; one region's successful test does not prove every simulator works.

Log-first troubleshooting

If Firestorm controls are disabled, confirm CAPS in OpenSim.log before clearing viewer cache. For 404 check Apache rewrite and ServiceBase. If backend saved a change but viewer reports failure check HTTP status and CAPS response. If reset does not refresh nearby viewers inspect DisplayNameUpdate and EventQueue. Remote Hypergrid UUIDs not found locally may be expected; correlate logs before diagnosing failure.

Adapt the example: do not reuse paths or credentials without verification.

# Simulateur :
grep -nEi 'DisplayNameCaps|DisplayNameSimModule|exception|ERROR' /chemin/vers/OpenSim.log | tail -n 120
# Web PHP/Apache : consulter le journal d’erreurs réel du vhost
# Backend, seulement si debug=true et droits de fichiers adaptés :
tail -n 100 /chemin/vers/displayname/logs/displaynames.log

Backup, history and operations

Back up display_names and display_name_history alongside ROBUST accounts and backend configuration. The change_delay_days restriction is enforced by the backend: 0 means no delay, 7 means seven days. Debug logs may include personal data and IPs; restrict access and retention, and disable unnecessary debugging in production.

Module source documentation and files

General log diagnosis method