enhancement
major
minor
defect
critical
major
minor
major
#30268
Systemumgebung: Herkunft der Konfigurationsvariablen anzeigen und Variablen aus der Administration setzen
Kontext
Die Konfiguration einer Anwendung enthält Konfigurationsvariablen (Aliase wie %STORAGE_PATH%). Ihre Definition kann festlegen, aus welcher Umgebungsvariablen bzw. Systemproperty der Wert kommt, und welche Vorgabe sonst gilt, z. B. ${env:tl_storage_path:%APP_ROOT%/WEB-INF/app-data}. Eine Variable ohne einen solchen Ausdruck ließ sich nur durch eine eigene Konfigurationsdatei der Installation ändern. Die Systemumgebung der Administration listete die Variablen nur mit ihrem aufgelösten Wert; welche Umgebungsvariable eine Konfigurationsvariable setzt, war nicht zu erkennen, da DefaultAliasManager den ${env:…}-Ausdruck beim Laden ersetzte und nur das Ergebnis behielt.
In einer einfachen Installation (WAR in einem Tomcat, Debian-Paket) ist der autoconf-Ordner der Installation (tl_autoconf_dir) für die Anwendung beschreibbar; der Service-Editor speichert dort bereits Dienstkonfigurationen.
Verhalten
- Jede Variable ist über die Umgebung setzbar: Eine Konfigurationsvariable, deren Definition keinen ${env:…}-Ausdruck enthält, wird implizit aus dem JNDI-Wert, der Systemproperty bzw. der Umgebungsvariablen tl_<name> gelesen: der Name der Variable ohne %`, in Kleinbuchstaben, jedes Zeichen außer Buchstaben, Ziffern und `_ durch _` ersetzt (%ATTIC_PATH%` → tl_attic_path, %LDAP_URL% → tl_ldap_url). Ihr Wert ersetzt die ganze Definition. Eine Variable mit ${env:…}-Ausdruck wird nur über die dort genannten Namen gesetzt. Programmatisch gesetzte Variablen (%APP_ROOT%, %APP_CONTEXT%, %LOCAL_HOST_NAME%) bleiben ausgenommen.
- Ansicht „Konfigurationsvariablen“ (React-Oberfläche, Administration → System, neben „Geheimnisse“): Sie zeigt für jede Konfigurationsvariable die Umgebungsnamen, über die sie gesetzt wird (ein impliziter Name ist gekennzeichnet), woher der aktuelle Wert stammt (JNDI, Systemproperty, Umgebungsvariable jeweils mit dem Namen, in der Anwendung gespeicherter Wert oder Definition), den aktuellen Wert, die Vorgabe der Definition, den gespeicherten Wert und ob ein Neustart nötig ist. Die Konfigurationsvariablen erscheinen nicht mehr in der Tabelle der Systemumgebung, die Systemproperties und VM-Argumente zeigt.
- Setzen aus der Anwendung: „Wert setzen“ und „Gespeicherten Wert entfernen“ speichern bzw. entfernen den Wert der ausgewählten Variable in der Datei variables.properties im autoconf-Ordner. Die Änderung wird erst nach einem Neustart wirksam; die Ansicht weist darauf hin, nennt die Datei und markiert Variablen mit ausstehender Änderung. Der autoconf-Ordner gehört zu einem Knoten; in einer Installation mit mehreren Knoten gilt ein so gesetzter Wert nur für diesen Knoten. Wird der letzte Wert entfernt, wird die Datei gelöscht.
- Vorrang: JNDI, dann Systemproperty, dann Umgebungsvariable, dann der in der Anwendung gespeicherte Wert, dann die Definition mit ihren Vorgaben. Ist die Variable über die Umgebung gesetzt, bietet die Ansicht das Setzen nicht an und nennt den Grund; ein gespeicherter, dadurch verdeckter Wert kann entfernt werden.
- Keine Geheimnisse: Variablen, deren Name einem der geschützten Muster entspricht, zeigen ihre Werte verdeckt und können weder gesetzt noch entfernt werden; Geheimnisse gehören in die Geheimnisablage (#30267).
Technische Hinweise
- AliasManager ist für die Zuordnung Variable → Umgebungsnamen zuständig und die einzige Stelle, die ${env:…} auswertet. Beim Auflösen hält er je konfigurierter Variable eine Beschreibung fest (AliasDefinition: Definition im Wortlaut, Umgebungsnamen, implizit oder explizit, Vorgabe, Herkunft AliasSource mit Namen, Wert beim Start, gespeicherter Wert, wirksamer Wert, ausstehende Änderung) und stellt sie über getDefinition(name) / getDefinitions() bereit. implicitEnvironmentName(name) bildet den impliziten Namen.
- canStoreValues(), storeValue(name, value), removeValue(name) und getStoredValuesFile() (Konstante STORED_VALUES_FILE) verwalten die Datei atomar; der Ordner wird bestimmt wie für den Service-Editor (tl_autoconf_dir, sonst WEB-INF/autoconf der Webanwendung) und bei Bedarf angelegt.
- Die Prüfung der geschützten Namen ist SystemEnvironmentBuilder.protectedNames() und wird von Systemumgebung und Konfigurationsvariablen gemeinsam genutzt.
- Die Ansicht admin/system/config-variables.view.xml (Dialog set-config-variable.view.xml) nutzt die TL-Script-Funktionen configVariable… (ConfigVariableFunctions).
- Entwickler-Artikel configuration-variables (com.top_logic.basic) beschreibt Definition, Umgebungsnamen, Vorrang und gespeicherte Werte.
Migration
- Eine Konfigurationsvariable, die eine Anwendung mit einem festen Wert ohne ${env:…}-Ausdruck überschreibt (z. B. <alias name="%STORAGE_PATH%" value="./data"/>), um einen über die Umgebung gesetzten Wert der Basisdefinition zu übergehen, wird jetzt dennoch durch tl_<name> aus JNDI, Systemproperty oder Umgebung ersetzt (hier tl_storage_path). Soll der feste Wert auch dann gelten, wenn die Umgebung tl_<name> setzt (etwa in einem Docker-Image, das tl_storage_path setzt), entfernt man die Variable aus der Umgebung der Installation bzw. setzt dort den gewünschten Wert.