Vergleichsreport

Diese Seite beschreibt, wie ein Webdesk mit mehreren Knoten (Cluster, "verteilter Betrieb") konfiguriert und betrieben wird und wie sich die Caches dabei verhalten. Sie richtet sich an Systemadministratoren und Consultants. Vorausgesetzt werden: alle Knoten greifen auf dieselbe Datenbank zu, ein erreichbarer Redis-Server und – bei Cache-Replikation über JMS – ein JMS-Broker. Die Schlüssel werden pro Knoten in der webdesk.properties gesetzt (siehe Seite This page describes how a Webdesk with several nodes (cluster, "distributed operation") is configured and operated, and how the caches behave in this setup. It is intended for system administrators and consultants. Prerequisites: all nodes access the same database, a reachable Redis server and, for cache replication via JMS, a JMS broker. The keys are set per node in webdesk.properties (see page "Konfigurationsdatei webdesk.properties und Umgebungsvariablen"). Ergänzend beschreiben Liste der Caches den Zweck der Caches, Aktive Jobs die Job-Überwachung inklusive Knotenstatus und Erweiterte Funktionen die Wartungsaktionen.

Überblick: Bausteine des Cluster-Betriebs

Baustein

Aufgabe

Schalter

Cache-Replikation (EhCache)

Gleicht die EhCache-Caches zwischen den Knoten ab und transportiert Dienstaufrufe an die anderen Knoten (Speichern von Jobs und Job-Triggern, Übernahme von Systemparametern, Veröffentlichung des Clusterstatus). Transport wahlweise RMI (Multicast) oder JMS.

isDistributed, useJmsReplication

Redis

Gemeinsamer Speicher und Nachrichtenkanal (Pub/Sub) für die als "repliziert" definierten Anwendungs-Caches

In addition, List of caches describes the purpose of the caches, Active Jobs describes job monitoring including node status, and Extended Tasks describes the maintenance actions.

Overview: building blocks of cluster operation

Cache für Datenbank-Entitäten. Anbieter global umschaltbarSitzungen lokal im Speicher

Building block	Purpose	Switch
Cache replication (EhCache)	Synchronizes the EhCache caches between the nodes and transports service calls to the other nodes (saving jobs and job triggers, applying system parameters, publishing the cluster status). Transport is either RMI (multicast) or JMS.	isDistributed, useJmsReplication
Redis	Shared store and message channel (Pub/Sub) for the application caches defined as "replicated" (Caffeine + Redis), für den Hibernate-Provider for the Hibernate provider redis-caffeine und für die HTTP-Sessions and for the HTTP sessions (Spring Session). Die Redis-Anbindung wird aufgebaut, wenn The Redis connection is set up when isDistributed=true oder or redis.useAsSessionStore=true gilt applies.	redis.*
Hibernate -Cache cache (Second-Level-Cache)	second-level cache)	Cache for database entities. The provider can be switched globally.	webdesk.hibernate.cache.provider
HTTP -Sessions	sessions	Sessions held locally in memory, in Redis (Spring Session) oder über den Tomcat-Session-Manageror via the Tomcat session manager.	redis.useAsSessionStore, META-INF/context.xml
Jobs	Zuordnung der Job-Trigger zu einem KnotenAssignment of job triggers to a node.	PoOptions.clusterNodes, Trigger-Feld "Ausführen auf Clusternode"

Bei

trigger field "Run on cluster node"

With isDistributed=false (Standard) ist jede Abstimmung zwischen Knoten abgeschaltet; die Caches arbeiten dann rein lokal. Ein gesetztes useJmsReplication wird ohne isDistributed=true ignoriert.

Grundkonfiguration eines Knotens

Eigenschaft

Erklärung

mögliche Wert(e)

isDistributed

Schaltet den verteilten Betrieb ein: Cache-Replikation, Redis-Anbindung für replizierte Caches, Cluster-Heartbeat und knotenspezifischer Workflow-Engine-Name. Muss auf allen Knoten gleich gesetzt sein

default), all coordination between nodes is switched off; the caches then work purely locally. A useJmsReplication that is set is ignored without isDistributed=true.

Basic configuration of a node

Text (StandardZahl (Standard

Property	Description	Possible value(s)
isDistributed	Switches on distributed operation: cache replication, Redis connection for replicated caches, cluster heartbeat and a node-specific workflow engine name. Must be set identically on all nodes.	true/false (Standarddefault: false)
useJmsReplication	Bei If true werden die EhCache-Caches über JMS repliziert, sonst über RMI mit Multicast-Erkennung. Nur wirksam bei isDistributed=true. Muss auf allen Knoten gleich gesetzt sein, the EhCache caches are replicated via JMS, otherwise via RMI with multicast discovery. Only effective with isDistributed=true. Must be set identically on all nodes.	true/false (Standarddefault: false, also i.e. RMI)
PoOptions.clusterNode	Name dieses Knotens; muss pro Knoten eindeutig sein. Ist kein Name gesetzt, zeigt der Clusterstatus LOCAL. Wird isDistributed=true per Umgebungsvariable oder JVM-Parameter gesetzt und weder dort noch in der webdesk.properties ein Knotenname angegeben, verwendet Webdesk beim Start die Umgebungsvariable HOSTNAME als Knotennamen. Ist isDistributed nur in der webdesk.properties gesetzt, findet diese Vorbelegung nicht statt.	Text, z.B. node1
PoOptions.clusterNodes	Liste aller Knotennamen des Clusters. Wird in der Maske "Systemparameter" (Bean PoOptions, Eigenschaft clusterNodes) gepflegt und gilt für alle Knoten. Die Einträge müssen exakt den PoOptions.clusterNode-Namen der Knoten entsprechen: Der Clusterstatus erwartet von jedem Eintrag eine Statusmeldung, der Name des aktuellen Knotens wird immer zusätzlich berücksichtigt. Das Job-Feld "Ausführen auf Clusternode" bietet die Liste nur an, wenn sie mehr als einen Eintrag enthält.	Liste von Namen (Standard: ClusterNode1)
WfStartup.engineName	Name der Workflow-Engine des Knotens. Wird der Standardname bei isDistributed=true nicht geändert, bildet Webdesk den Namen aus Standardname und Knotenname (webdeskshark_<Knotenname>); im Normalfall muss der Schlüssel daher nicht gesetzt werden.	of this node; must be unique per node. If no name is set, the cluster status shows LOCAL. If isDistributed=true is set via an environment variable or JVM parameter and no node name is given there or in webdesk.properties, Webdesk uses the environment variable HOSTNAME as the node name at startup. If isDistributed is set only in webdesk.properties, this pre-assignment does not take place.	Text, e.g. node1
PoOptions.clusterNodes	List of all node names of the cluster. Maintained in the "System parameters" mask (bean PoOptions, property clusterNodes) and valid for all nodes. The entries must match exactly the PoOptions.clusterNode names of the nodes: the cluster status expects a status message from every entry, and the name of the current node is always taken into account in addition. The job field "Run on cluster node" offers the list only if it contains more than one entry.	List of names (default: ClusterNode1)
WfStartup.engineName	Name of the workflow engine of the node. If the default name is not changed with isDistributed=true, Webdesk builds the name from the default name and the node name (webdeskshark_<node name>); normally this key therefore does not need to be set.	Text (default: webdeskshark)
webdesk.cluster.heartbeatIntervalSeconds	Intervall in Sekunden, in dem ein Knoten seinen Clusterstatus und seinen Job-Überwachungsstand an die anderen Knoten veröffentlicht (auch sofort beim Start). Läuft nur bei Interval in seconds at which a node publishes its cluster status and its job monitoring snapshot to the other nodes (also immediately at startup). Runs only with isDistributed=true. 0 schaltet den Heartbeat ab, ein negativer Wert verwendet den Standard.	switches the heartbeat off, a negative value uses the default.	Number (default: 30)
webdesk.cluster.skipIdleJobMonitoringSnapshots	Bei true veröffentlicht ein Knoten ohne Jobs und mit gestopptem Scheduler im Heartbeat keinen Job-ÜberwachungsstandIf true, a node without jobs and with a stopped scheduler does not publish a job monitoring snapshot in the heartbeat.	true/false (Standarddefault: true)

HinweisNote: Die Schlüssel The keys isDistributed, useJmsReplication, PoOptions.clusterNode, WfStartup.engineName, webdesk.cacheReplication.RMI.peerProvider.properties und and webdesk.cacheReplication.JMS.peerProvider.properties können auch als JVM-Parameter oder Umgebungsvariable gesetzt werden. Der Name der Umgebungsvariable lautet WD_ plus Schlüssel in Großbuchstaben, Punkte werden zu Unterstrichen (z.B can also be set as a JVM parameter or environment variable. The environment variable name is WD_ plus the key in upper case, with dots replaced by underscores (e.g. WD_ISDISTRIBUTED, WD_POOPTIONS_CLUSTERNODE). Leere Umgebungsvariablen werden ignoriertEmpty environment variables are ignored.

Cache -Replikationreplication: RMI oder JMS

Der Transport gilt global für alle replizierten EhCache-Caches und wird über useJmsReplication gewählt. Zusätzlich nutzt Webdesk die Replikation, um Dienstaufrufe an die anderen Knoten zu senden. Das betrifft das Speichern von Jobs und Job-Triggern, die Übernahme von Systemparametern (Neu-Injektion der Bean-Eigenschaften) und die Veröffentlichung des Clusterstatus. Ist die Replikation gestört, erreichen diese Änderungen die anderen Knoten nicht.

Eigenschaft

Erklärung

mögliche Wert(e

or JMS

The transport applies globally to all replicated EhCache caches and is selected with useJmsReplication. In addition, Webdesk uses the replication to send service calls to the other nodes. This concerns saving jobs and job triggers, applying system parameters (re-injection of the bean properties) and publishing the cluster status. If the replication is disturbed, these changes do not reach the other nodes.

StandardStandardVorlageListe von Cache-Namen (Standard: leerStandard

Property	Description	Possible value(s)
webdesk.cacheReplication.RMI.peerProvider.properties	Peer -Erkennung bei RMI. Standard ist die automatische Erkennung über Multicast. timeToLive legt die Reichweite fest: 0 gleicher Host, 1 gleiches Subnetz, 32 gleicher Standort, 64 gleiche Region, 128 gleicher Kontinent, 255 unbeschränkt. Die Knoten müssen sich also in derselben Multicast-Gruppe befinden und Multicast muss im Netzwerk erlaubt sein.	discovery with RMI. The default is automatic discovery via multicast. timeToLive defines the reach: 0 same host, 1 same subnet, 32 same site, 64 same region, 128 same continent, 255 unrestricted. The nodes must therefore be in the same multicast group and multicast must be allowed in the network.	Default: peerDiscovery=automatic,multicastGroupAddress=230.0.0.1,multicastGroupPort=4446,timeToLive=1
webdesk.cacheReplication.peerListener.properties	Einstellungen des RMI-Listeners (nur bei RMI).	Settings of the RMI listener (RMI only).	Default: socketTimeoutMillis=120000
webdesk.cacheReplication.JMS.peerProvider.properties	Verbindung zum JMS-Broker (nur bei JMS): Adresse des Brokers sowie Benutzer und Passwort eines gültigen Broker-Zugangs. Webdesk startet keinen eigenen Broker. Die Namen von Topic und Queue sind fest vorgegeben und nicht änderbar. Der Beispielwert in der Vorlage enthält Standard-Zugangsdaten, die durch die echten Zugangsdaten zu ersetzen sind.	Connection to the JMS broker (JMS only): address of the broker as well as user and password of a valid broker account. Webdesk does not start a broker of its own. The names of the topic and queue are fixed and cannot be changed. The example value in the template contains default credentials, which must be replaced by the real credentials.	Template: providerURL=tcp://localhost:61616/,userName=<user>,password=<password>
webdesk.cacheReplication.excludedCaches	Komma-getrennte Liste von Cache-Namen, die nicht repliziert werden sollen. Gilt für die Comma-separated list of cache names that are not to be replicated. Applies to the caches defined in ehcache.xml-Dateien definierten Caches und, im Hibernate-Modus ehcache2, für Hibernate-Regionen.	files and, in Hibernate mode ehcache2, to Hibernate regions.	List of cache names (default: empty)
webdesk.cacheReplication.listener.replicatePuts, .replicateUpdates, .replicateUpdatesViaCopy, .replicateRemovals, .replicateAsynchronously	Was und wie repliziert wirdWhat is replicated and how.	true/false (Standarddefault: jeweils true in each case)
webdesk.cacheReplication.maxElementsInMemory, .timeToIdleSeconds, .timeToLiveSeconds, .eternal, .overflowToDisk	Vorgabewerte für EhCache-Caches ohne eigene Definition.	Default values for EhCache caches without their own definition.	Default: 100 / 300 / 300 / false / true

AchtungWarning: Setting webdesk.cacheReplication.listener.replicatePuts=false global zu setzen ist nicht zulässig. Der Versand von Dienstaufrufen zwischen den Knoten beruht darauf, dass das Ablegen eines Eintrags im internen Kommunikations-Cache repliziert wird; mit replicatePuts=false würden Job-Änderungen, Systemparameter und Clusterstatus nicht mehr bei den anderen Knoten ankommen. Achtung: Der ältere Schlüssel globally is not permitted. The sending of service calls between the nodes relies on the put of an entry into the internal communication cache being replicated; with replicatePuts=false, job changes, system parameters and the cluster status would no longer arrive at the other nodes.

Warning: The older key webdesk.cacheReplication.peerProvider.properties (ohne without RMI) wird nicht mehr ausgewertet. Mit ihm gesetzte Multicast-Adressen oder -Ports gelten nicht; es greift der Standard is no longer evaluated. Multicast addresses or ports set with it do not apply; the default (230.0.0.1, Port port 4446) . Die Vorgabewerte für Caches können zusätzlich durch eine Datei defaultCacheConfiguration.properties im Klassenpfad takes effect.

The default values for caches can additionally be overridden by a file defaultCacheConfiguration.properties on the classpath (WEB-INF/classes) übersteuert werden; sie hat Vorrang vor der ; it takes precedence over webdesk.properties. Dass overflowToDisk standardmäßig aktiv ist, kann bei großen Caches zu höheren Antwortzeiten führen, weil Einträge dann von der Platte gelesen werden; Caches mit eigener Bean-Definition können dies mit der Bean-Eigenschaft overflowToDisk abschalten (BeispielThe fact that overflowToDisk is active by default can lead to longer response times for large caches, because entries are then read from disk; caches with their own bean definition can switch this off with the bean property overflowToDisk (example: PtmPermissionCacheBean.overflowToDisk=false in der webdesk.properties). Die Überschreibung per <Bean>.<Eigenschaft> wirkt nur auf Spring-Cache-Beans, nicht auf die Regionen der ehcache.xml-Dateien für den Hibernate-Cache.

Redis

Redis wird für Sessions The override via <Bean>.<property> only works for Spring cache beans, not for the regions of the ehcache.xml files used for the Hibernate cache.

Redis

Redis is used for sessions (Spring Session), für replizierte Anwendungs-Caches (Caffeine als lokale Ebene, Redis als gemeinsame Ebene, Ungültigkeitsmeldungen über den Pub/Sub-Kanal for replicated application caches (Caffeine as the local level, Redis as the shared level, invalidation messages via the Pub/Sub channel webdesk:cache-sync) und für den Hibernate-Provider and for the Hibernate provider redis-caffeine (Kanal channel webdesk:hibernate-cache-coherence) verwendet. Die Verbindung wird aufgebaut, sobald . The connection is set up as soon as isDistributed=true oder or redis.useAsSessionStore=true gilt applies. Ist weder If neither redis.connection.url noch nor redis.clusterNodes gesetzt is set, verbindet sich Webdesk mit connects to localhost Port port 6379.

z.B

Eigenschaft	Erklärung	mögliche Wert(e Property	Description	Possible value(s)
redis.useAsSessionStore	Bei If true werden die HTTP-Sessions über Spring Session in Redis gehalten, the HTTP sessions are held in Redis via Spring Session.	true/false (Standarddefault: false)
redis.connection.url	Adresse eines einzelnen Redis-Servers. Übernommen werden Host, Port und Datenbank-Nummer; ein in der URL enthaltenes Passwort wird nur verwendet, wenn Address of a single Redis server. Host, port and database number are taken over; a password contained in the URL is used only if redis.connection.password leer ist is empty.	ze.Bg. redis://redis-host:6379/0 (Standarddefault: leerempty, dann then localhost:6379)
redis.clusterNodes	Komma-getrennte Liste der Knoten eines Redis-Clusters. Ist der Wert gesetzt, hat er Vorrang vor Comma-separated list of the nodes of a Redis cluster. If set, it takes precedence over redis.connection.url; die Zeitüberschreitung für Redis-Befehle beträgt dann 2 Sekunden.	the timeout for Redis commands is then 2 seconds.	e.g. host1:6379,host2:6379 (Standarddefault: leerempty)
redis.connection.password	Passwort für Password for Redis. Nicht in Dokumentation, Tickets oder Logs weitergebenDo not pass it on in documentation, tickets or logs.	<your-redis-password> (Standarddefault: leerempty)
redis.credentials.encrpted	Bei If true ist , redis.connection.password mit dem Webdesk-Verfahren verschlüsselt abgelegt. Der Schlüsselname ist im Produkt so geschrieben is stored encrypted with the Webdesk method. The key name is spelled this way in the product ("encrpted") und muss genau so verwendet werdenand must be used exactly like this.	true/false (Standarddefault: false)
redis.session.cookie.jvmRoute	Route -Suffix des Session-Cookies JSESSIONID für Load Balancer, die über dieses Suffix routen (z.B. Apache mit mod_jk, Worker-Name wie worker2). Ist der Wert leer, liest Webdesk das Attribut jvmRoute des Engine-Elements aus der suffix of the session cookie JSESSIONID for load balancers that route by this suffix (e.g. Apache with mod_jk, worker name such as worker2). If the value is empty, Webdesk reads the jvmRoute attribute of the Engine element from the Tomcat conf/server.xml des Tomcat. Der Wert ist nicht automatisch gleich . The value is not automatically the same as PoOptions.clusterNode. Findet sich keine Route, wird im Log gewarnt und das Cookie ohne Suffix geschriebenIf no route is found, a warning is logged and the cookie is written without a suffix.	Text (Standarddefault: leerempty)

Die The redis.*-Schlüssel können auch als JVM-Parameter oder Umgebungsvariable gesetzt werden (z.B keys can also be set as a JVM parameter or environment variable (e.g. WD_REDIS_USEASSESSIONSTORE, WD_REDIS_CONNECTION_URL); diese haben Vorrang vor der these take precedence over webdesk.properties.

Hibernate -Cache cache (Second-Level-Cache)

Der Anbieter des Hibernate-Caches wird mit

second-level cache)

The provider of the Hibernate cache is selected with webdesk.hibernate.cache.provider in der webdesk.properties gewählt. Die Wahl gilt global und unabhängig von isDistributed. Die Variante redis-caffeine steht seit . The choice applies globally and independently of isDistributed. The redis-caffeine variant has been available as an option since Webdesk 4.64 optional zur Verfügung.

Wert

Wirkung

.

Value	Effect
ehcache2 (Standard, auch bei leerem Wertdefault, also for an empty value)	EhCache-basierter Cachebased cache; bei with isDistributed=true über replicated via RMI oder or JMS repliziert. Die Regionen sind in den . The regions are defined in the ehcache.xml-Dateien der Module definiert files of the modules.
redis-caffeine	Redis als maßgeblicher gemeinsamer Speicher, ergänzt um einen lokalen Caffeine-Nahbereichs-Cache. Benötigt eine Redis-Anbindung, also isDistributed=true oder as the authoritative shared store, supplemented by a local Caffeine near cache. Requires a Redis connection, i.e. isDistributed=true or redis.useAsSessionStore=true; sonst scheitert der Start mit der Meldung, dass die Redis-Verbindung nicht verfügbar ist.
disabled	Schaltet Second-Level-Cache und Query-Cache ab.

Ein anderer Wert verhindert den Start mit einer Fehlermeldung, die die erlaubten Werte nennt.

Regeln für den Betrieb

Alle Knoten einer Umgebung müssen denselben Wert verwenden.

Eine Änderung des Werts erfordert einen Neustart der gesamten Umgebung; ein Mischbetrieb verschiedener Anbieter ist zu vermeiden.

Der Redis-Server muss für redis-caffeine die Eviction-Richtlinie maxmemory-policy noeviction (oder ein gleichwertiges, dokumentiertes Verhalten bei verwaltetem Redis) haben. Webdesk prüft dies beim Start per CONFIG GET maxmemory-policy und bricht den Start bei anderen Richtlinien (z.B

otherwise startup fails with a message that the Redis connection is not available.
disabled	Switches off the second-level cache and the query cache.

Any other value prevents startup with an error message that names the permitted values.

Rules for operation

• All nodes of an environment must use the same value.
• Changing the value requires a restart of the entire environment; mixed operation of different providers is to be avoided.
• For redis-caffeine, the Redis server must have the eviction policy maxmemory-policy noeviction (or an equivalent, documented behavior for managed Redis). Webdesk checks this at startup using CONFIG GET maxmemory-policy and aborts startup for other policies (e.g. allkeys-lru, volatile-lru) oder bei verweigertem or if CONFIG GET ab. Auch mit noeviction sollte der Speicherverbrauch von Redis überwacht werden, da ein voller Redis zum Ausfall führt.
• Lokale EhCache2-Cache-Dateien (Disk-Stand) dürfen beim Wechsel des Anbieters nicht weiterverwendet werden.

Umstellung auf redis-caffeine

Wert für

• is denied. Even with noeviction, the memory consumption of Redis should be monitored, because a full Redis leads to an outage.
• Local EhCache2 cache files (disk state) must not be reused when the provider is changed.

Switching to redis-caffeine

1. Define the value for webdesk.hibernate.cache.provider für die gesamte Umgebung festlegen und ein Wartungsfenster planen, damit kein Mischbetrieb entsteht. Prüfen, dass Redis mit for the entire environment and plan a maintenance window so that no mixed operation occurs.
2. Check that Redis runs with maxmemory-policy noeviction arbeitet.
3. Die Redis-Schlüssel des Hibernate-Caches (Präfix Delete the Redis keys of the Hibernate cache (prefix wd:hibernate:l2:) vor dem Start löschen, da frühere Einträge nicht kompatibel sind. Beispiel für einen einzelnen Redis-Server (bei Redis Cluster pro Primärknoten ausführenbefore starting, because earlier entries are not compatible. Example for a single Redis server (for Redis Cluster, run it per primary node):

   redis-cli --scan --pattern 'wd:hibernate:l2:*' | xargs -r redis-cli del

4. Den Wert Set the value in der webdesk.properties aller Knoten setzen und die Knoten starten.
5. Im Log prüfen, dass keine dauerhafte Flut von Decodier-Warnungen zu Hibernate-Cache-Schlüsseln auftritt.

Rückstellung oder Wechsel auf ehcache2 / disabled

1. Alle Knoten stoppen.
2. Bei bisherigem Modus redis-caffeine die Schlüssel of all nodes and start the nodes.
3. Check in the log that there is no persistent flood of decoding warnings for Hibernate cache keys.

Rolling back or switching to ehcache2 / disabled

1. Stop all nodes.
2. If the previous mode was redis-caffeine, delete the keys wd:hibernate:l2:* löschen.
3. Den Wert Set the value in der webdesk.properties aller Knoten auf den Zielwert setzen.
4. Alle Knoten in einem Zug wieder starten.

Feineinstellung des Nahbereichs-Caches

1. of all nodes to the target value.
2. Start all nodes again in one go.

Tuning the near cache (redis-caffeine)

Veränderbare Entitäten werden standardmäßig lokal zwischengespeichert; Redis bleibt maßgeblich. Wird ein Ereignis verpasst, kann ein Knoten einen Wert höchstens bis zum Ablauf von valueTtlMillis veraltet liefern. Die folgenden Schlüssel sind optional; die Standardwerte sind für den Normalbetrieb ausgelegt. Wo diese Schlüssel in einer Installation abgelegt werden, sollte mit dem Webdesk-Support abgestimmt werden.

Eigenschaft

Erklärung

mögliche Wert(e

Mutable entities are cached locally by default; Redis remains authoritative. If an event is missed, a node can serve a value that is out of date for at most valueTtlMillis. The following keys are optional; the default values are designed for normal operation. Where these keys are stored in an installation should be agreed with Webdesk support.

Zahl (StandardZahl (StandardZahl (StandardCLEAR (StandardListe (Standard: leerListe (Standard: leer

Property	Description	Possible value(s)
wd.cache.hibernate.nearCache.valueTtlMillis	Gültigkeit eines lokal gelesenen Werts in Millisekunden.	Validity of a locally read value in milliseconds.	Number (default: 3000)
wd.cache.hibernate.nearCache.coherenceStateTtlMillis	Dauer in Millisekunden, für die der lokal beobachtete Kohärenzzustand vorgehalten wird.	Time in milliseconds for which the locally observed coherence state is retained.	Number (default: 120000)
wd.cache.hibernate.nearCache.maxEntries	Maximale Anzahl lokaler Einträge.	Maximum number of local entries.	Number (default: 20000)
wd.cache.hibernate.nearCache.reconnectionStrategy	Verhalten nach einem Verbindungsabbruch zu Redis: lokale Werte werden verworfen. Die Werte LOAD und NONE werden abgelehnt.	Behavior after a connection loss to Redis: local values are discarded. The values LOAD and NONE are rejected.	CLEAR (default)
wd.cache.hibernate.nearCache.excludedMutableRegions	Komma-getrennte Liste von Regionen, die nie lokal gelesen werden dürfen (für besonders konsistenzkritische Regionen).	Comma-separated list of regions that must never be read locally (for particularly consistency-critical regions).	List (default: empty)
wd.cache.hibernate.nearCache.queryRegions	Komma-getrennte Liste von Query-Regionen, für die lokales Lesen erlaubt wird.	Comma-separated list of query regions for which local reading is allowed.	List (default: empty)
wd.cache.hibernate.region.entryTtlMillis	Lebensdauer eines Eintrags Lifetime of an entry in Redis in Millisekundenmilliseconds.	Zahl Number (Standarddefault: 3600000)
wd.cache.hibernate.readWrite.softLockTtlMillis	Lebensdauer der Soft-Locks Lifetime of the soft locks in Redis in Millisekundenmilliseconds.	Zahl Number (Standarddefault: 60000)

Die Kennzahlen The metrics webdesk.hibernate.l2.redis.publish.failures, webdesk.hibernate.l2.redis.event.apply.failures und and webdesk.hibernate.l2.redis.subscription.disconnects sollten im Normalbetrieb bei 0 bleiben, should stay at 0 during normal operation; webdesk.hibernate.l2.redis.near.cache.disabled sollte should be 0 sein.

HTTP -Sessions im Cluster

Welche Session-Art aktiv ist, zeigt die Maske "Clusterstatus" im Feld "Session-Mode" (siehe unten). Es gibt zwei voneinander unabhängige Einstellungen:

Spring Session mit Redis: aktiv bei

sessions in the cluster

The "Session mode" field of the "Cluster Status" mask shows which type of session handling is active (see below). There are two independent settings:

• Spring Session with Redis: active with redis.useAsSessionStore=true (Standarddefault: false). Das Session-Cookie bleibt JSESSIONID, optional mit Route-Suffix The session cookie remains JSESSIONID, optionally with a route suffix (redis.session.cookie.jvmRoute). Bei einem Knotenausfall findet der verbleibende Knoten die Session auch dann, wenn das Cookie noch das Suffix des ausgefallenen Knotens trägt. Bestimmte Session-Attribute werden bewusst nicht in Redis abgelegt, sondern bleiben auf dem Knoten, der sie angelegt hat (u.a. die Zustände von Cocoon-Formularen und Flowscripts, die Vaadin-Anwendung HR Expert, der angemeldete und der gewechselte Benutzer, der Skin). Der Load Balancer sollte Anfragen einer Session daher möglichst auf demselben Knoten halten.Tomcat-Session-Manager If a node fails, the remaining node finds the session even if the cookie still carries the suffix of the failed node. Certain session attributes are deliberately not stored in Redis but stay on the node that created them (among others the states of Cocoon forms and flowscripts, the Vaadin application HR Expert, the logged-in and the switched user, the skin). The load balancer should therefore assign the requests of a session to the same node where possible (sticky routing).
• Tomcat session manager (memcached-session-manager mit with Redis): wird ausschließlich über ein is switched on exclusively via a <Manager className="de.javakaffee.web.msm.MemcachedBackupSessionManager" .../>-Element element in der the META-INF/context.xml des of Webdesk eingeschaltet. In der im WAR ausgelieferten the context.xml ist dieses Element auskommentiert. Das Docker-Image des Webdesk bringt dagegen eine eigene delivered in the WAR, this element is commented out. The Webdesk Docker image, however, brings its own context.xml mit, die in die Web-Anwendung kopiert wird und das Element aktiv enthält (mit , which is copied into the web application and contains the element in active form (with memcachedNodes="redis://redis"); die Bibliotheken des Session-Managers sind im Image vorhanden. Die Maske "Clusterstatus" meldet the libraries of the session manager are present in the image. The "Cluster Status" mask reports "memcached-session-manager / Redis" , sobald das Element in der as soon as the element is found in the context.xml gefunden wird, auch wenn zusätzlich , even if redis.useAsSessionStore=true gesetzt ist.

Achtung: Vor der Inbetriebnahme muss pro Umgebung geklärt und im "Session-Mode" überprüft werden, welcher Mechanismus tatsächlich aktiv ist. Vor allem bei Docker-Betrieb ist die mitgelieferte context.xml zu beachten.

Für Formulare gibt es zusätzlich die Systemparameter enableFormStateClusterFailover (Standard: false) und useSessionToStoreFormState (Standard: true) der Bean PoOptions. Bei aktiviertem Failover wird der zuletzt gespeicherte Zustand bestimmter Formulare nach einem Knotenwechsel wiederhergestellt; mit useSessionToStoreFormState=true wird der Zustand in der Session (und damit in Redis) abgelegt, sonst in einem replizierten EhCache-Bereich.

Jobs im Cluster

• Ob und mit wie vielen Threads auf einem Knoten Jobs ausgeführt werden, legen PoJobServiceTarget.active und noOfSchedulerThreads fest (siehe Systemparameter Portal & Organisation).
• Arbeitet Webdesk als Cluster (isDistributed=true, mehr als ein Eintrag in PoOptions.clusterNodes und der eigene Knotenname ist enthalten), erscheint im Job-Editor bei den Triggern das Feld "Ausführen auf Clusternode". Ein Trigger wird nur auf dem Knoten eingeplant, dessen Name dort ausgewählt ist. Ein Trigger ohne Knotenzuordnung wird in dieser Konstellation auf keinem Knoten eingeplant (ausgenommen das einmalige Starten über "Job starten").
• Die Überwachung der Jobs aller Knoten beschreibt Aktive Jobs.

Was nicht automatisch zwischen den Knoten abgeglichen wird

Bereich

Verhalten und Maßnahme

MetaForm-Cache

Ist von der Replikation ausgenommen. Nach Änderungen an Formulardefinitionen, die nicht auf allen Knoten übernommen wurden, in der Maske "Erw. Funktionen" die Aktion "MetaForm-Cache auf allen Cluster-Knoten ungültig machen" ausführen. Sie leert den MetaForm-Cache auf dem aktuellen und auf den übrigen Knoten.

Weitere nicht replizierte Caches

Einige Caches sind bewusst lokal: unter anderem die Workflow-Prozessdefinitions-Caches

• is additionally set.

Warning: Before going live, it must be clarified per environment, and verified in the "Session mode", which mechanism is actually active. With Docker operation in particular, the supplied context.xml must be taken into account.

For forms there are also the system parameters enableFormStateClusterFailover (default: false) and useSessionToStoreFormState (default: true) of the bean PoOptions. With failover enabled, the most recently saved state of certain forms is restored after a node switch; with useSessionToStoreFormState=true the state is stored in the session (and thus in Redis), otherwise in a replicated EhCache region.

Jobs in the cluster

• Whether and with how many threads jobs are executed on a node is determined by PoJobServiceTarget.active and noOfSchedulerThreads (see System parameters Portal & Organization).
• If Webdesk works as a cluster (isDistributed=true, more than one entry in PoOptions.clusterNodes and the own node name is contained), the job editor shows the field "Run on cluster node" for the triggers. A trigger is scheduled only on the node whose name is selected there. In this constellation, a trigger without a node assignment is scheduled on no node (except for the one-time start via "Start Job").
• The monitoring of the jobs of all nodes is described in Active Jobs.

What is not synchronized automatically between the nodes

Der Volltextindex liegt im lokalen Dateisystem jedes Knotens und wird beim Start des Knotens aktualisiert (Schlüssel

Area	Behavior and measure
MetaForm cache	Is excluded from the replication. After changes to form definitions that were not picked up on all nodes, run the action "Invalidate MetaForm cache on all cluster nodes" in the "Extended Tasks" mask. It clears the MetaForm cache on the current node and on the other nodes.
Other non-replicated caches	Some caches are deliberately local: among others the workflow process definition caches (webdesk_processdefinitions, webdesk_processdefinitions2hide, webdesk_wfprocessdefinitiondao_methodcache), die CMIS-Sitzungen der Dokumentenverwaltung und der Cache the CMIS sessions of document management and the cache at.workflow.webdesk.po.STATIC_NON_CLUSTERED. Änderungen daran wirken auf jedem Knoten nur lokal; siehe Erweiterte Funktionen (Workflow-Cache aktualisieren) und Changes to them take effect only locally on each node; see Extended Tasks (refresh workflow cache) and Job refresh Cache.
Lucene -Suchindex	search index	The full-text index resides in the local file system of each node and is updated when the node starts (key webdesk.luceneIndexing, Standarddefault: true). Die Aktionen The actions "Refresh Lucene -Suchindex aktualisieren" und "Lucene-Suchindex bereinigensearch index" and "Clean Lucene search index" in "Erw. Funktionen" wirken nur auf dem Knoten, auf dem sie ausgeführt werden. Der Unterordner des Index ist standardmäßig zufällig; mit dem JVM-Parameter Extended Tasks" only affect the node on which they are executed. The subfolder of the index is random by default; it can be fixed with the JVM parameter webdesk.lucene.index.subdir kann er festgelegt werden.	Menüs, Berechtigungen und weitere Caches per Hand leeren	Die Aktionen zum Leeren in der Maske "Liste der Caches" und in "Erw. Funktionen" werden auf dem Knoten ausgeführt, auf dem sie aufgerufen werden. Eine gezielte Weitergabe an die anderen Knoten ist nur bei der MetaForm-Aktion vorgesehen; bei sonstigen Caches hängt die Wirkung auf andere Knoten davon ab, ob der Cache repliziert wird (Spalte .
Clearing menus, permissions and other caches by hand	The clearing actions in the "List of caches" mask and in "Extended Tasks" are executed on the node on which they are called. Targeted forwarding to the other nodes is provided only for the MetaForm action; for other caches, the effect on other nodes depends on whether the cache is replicated (column "Distributed").
Session -Attribute	Siehe Abschnitt "HTTP-Sessions im Cluster".

Maske "Liste der Caches"

attributes

See section "HTTP sessions in the cluster".

"List of caches" mask (po_showCaches)

Die Maske zeigt alle Caches des Knotens, auf dem die Anfrage landet. Mit dem Textfeld "Zeige nur Caches deren Namen folgenden Text beinhalten" kann die Liste gefiltert werden. Je Cache werden angezeigt The mask shows all caches of the node that receives the request. The list can be filtered with the text field "Show only caches which names contain". For each cache, the following are shown: "Name", "EinträgeEntries", "EffizienzEfficiency" (Trefferquote hit rate in Prozentpercent), "Cache Typtype", "Distributed" sowie die Konfiguration (maximale Einträge, Time-to-idle, Time-to-and the configuration (maximum entries, time to idle, time to live, eternal). Mit der Option "Anzeige Speicherverbrauch" werden zusätzlich die Spalten "SpeicherWith the option "Display memory consumption", the columns "Memory, in KB" und and "Max. SpeicherMemory, in KB" sowie die Summen berechnet.

Spalte

as well as the sums are additionally calculated.

Column "Distributed"	Bedeutung	Meaning
Local	EhCache -Cache ohne Replikations-Listener: wird nicht zwischen Knoten abgeglichen.	Replicated	EhCache-Cache mit RMI-/JMS-Replikation oder Caffeine+Redis-Cache mit Abgleich über cache without a replication listener: is not synchronized between nodes.
Replicated	EhCache cache with RMI/JMS replication, or Caffeine+Redis cache synchronized via Redis.
Caffeine (Local)	Caffeine -Cache ohne Abgleich über cache without synchronization via Redis.
Terracotta-clustered / Unknown	EhCache -Cache mit Terracotta-Anbindung bzw. nicht erkannter Cache-Typ.

Ist der verteilte Betrieb aktiv, zeigt die Maske zusätzlich den Text "Diese Instanz ist Teil eines Clusters und hat den Namen" mit dem Knotennamen und die Schaltfläche "Anzeige Replikationsmitglieder". Sie listet die der Replikation bekannten Partner (bei RMI URL und GUID, bei JMS den Namen); sind keine Partner bekannt, erscheint

cache with a Terracotta connection, or an unrecognized cache type.

If distributed operation is active, the mask additionally shows the text "This webdesk instance is part of a cluster having the name" with the node name and the button "Show Replication Peers". It lists the partners known to the replication (with RMI URL and GUID, with JMS the name); if no partners are known, "No Caching Peers available" appears. Mit "Leeren aller Caches" bzw. dem Symbol "Cache leeren" je Zeile werden Caches des aktuellen Knotens geleert (nach dem Leeren aller Caches ist der Workflow-Cache zu aktualisieren, siehe Liste der Caches).

Maske "Clusterstatus" (po_showClusterStatus)

Beim Öffnen veröffentlicht der Knoten seinen eigenen Status und wartet bis zu 2,5 Sekunden darauf, dass die Meldungen der konfigurierten Knoten eintreffen. Erscheinen danach konfigurierte Knoten weiterhin als fehlend, zeigt die Maske den Hinweis "Die Cluster-Replikation ist noch im Aufbau." mit den Namen der "Konfigurierte Knoten noch nicht sichtbar". Im Normalbetrieb senden alle Knoten ihren Status im Heartbeat (Standard: alle 30 Sekunden).

Die Kopfzeile zeigt "Clusterübersicht" (antwortende Knoten / konfigurierte Knoten), die Anzahl "Veraltet" und "Fehlt" sowie die Topologie:

"Cluster-Modus": "Verteilt" oder "Einzelserver".

"Cache-Replikations-Topologie

With "Clear all caches" or the "Clear cache" icon per row, caches of the current node are cleared (after clearing all caches, the workflow cache has to be refreshed, see List of caches).

"Cluster Status" mask (po_showClusterStatus)

When opened, the node publishes its own status and waits up to 2.5 seconds for the messages of the configured nodes to arrive. If configured nodes still appear as missing afterwards, the mask shows the message "Cluster replication is still warming up." with the names under "Configured nodes not visible yet". During normal operation, all nodes send their status in the heartbeat (default: every 30 seconds).

The header line shows "Cluster summary" (responding nodes / configured nodes), the counts "Stale" and "Missing", and the topology:

• "Cluster mode": "Distributed" or "Single-server".
• "Cache replication topology": "RMI", "JMS" oder or "KeineNone".
• "Session -Modemode": "Spring Session / Redis", "memcached-session-manager / Redis", "Lokal im Speicher" oder "Unbekannt".

Die Tabelle listet je Knoten "Cluster-Knoten", "Status

• Local in-memory" or "Unknown".

The table lists per node "Cluster node", "State", "Job -Serviceservice" (gestartet oder gestopptstarted or stopped), "Threads", "Aktualisiert amRefreshed at", "Aktive SessionsActive sessions", "Aktive JobsActive jobs", "Laufende JobsExecuting jobs", Speicher memory (freifree, belegtused, maximalmaximum) sowie as well as "Version", "Revision" und and "Branch". Abweichende Versionen zwischen den Knoten sind in den Spalten Differing versions between the nodes are immediately visible in the columns "Version", "Revision" und and "Branch" sofort erkennbar. Die Werte in der Spalte "Status":

Status	Bedeutung
CURRENT	Der Knoten, dessen Maske gerade angezeigt wird.
RESPONDING	Konfigurierter Knoten, dessen letzte Statusmeldung nicht älter als 180 Sekunden ist.
STALE	Die letzte Statusmeldung ist älter als 180 Sekunden (mögliche Ursachen: Knoten ausgefallen, Heartbeat abgeschaltet oder Replikation unterbrochen).
MISSING	Der Knoten steht in PoOptions.clusterNodes, es liegt aber keine Statusmeldung vor: Der Knoten hat noch nie gemeldet (nicht gestartet, anderer Name, Replikation funktioniert nicht) oder seine letzte Meldung ist verfallen (Statusmeldungen werden nach 300 Sekunden aus dem Cache entfernt, ein ausgefallener Knoten wechselt also von STALE nach MISSING).
OBSERVED_ONLY	Der Knoten sendet Status, steht aber nicht in PoOptions.clusterNodes (z.B. Schreibweise des Namens oder fehlender Eintrag).

Typische Symptome und Prüfungen

Symptom

Prüfung

Der Eintrag "ClusterNode1" oder ein Knoten steht dauerhaft auf MISSING, obwohl alle Knoten laufen

PoOptions.clusterNodes enthält noch den Standardwert oder Namen, die von PoOptions.clusterNode abweichen. Namen auf allen Knoten und in der Liste abgleichen.

Andere Knoten sind nicht sichtbar (MISSING/STALE), Topologie zeigt "Keine"

isDistributed=true auf allen Knoten und Neustart? Bei RMI: gleiche Multicast-Gruppe und Port, Multicast im Netz erlaubt, timeToLive passend. Bei JMS: Broker erreichbar, Zugangsdaten gültig, auf allen Knoten useJmsReplication=true. In der Maske "Liste der Caches" die Replikationsmitglieder prüfen.

Änderung an einem Job oder Systemparameter wirkt nur auf einem Knoten

Die Weitergabe läuft über die Cache-Replikation. Clusterstatus und Replikationsmitglieder prüfen; replicatePuts darf nicht auf false stehen.

Ein Job läuft auf keinem Knoten

Trigger ohne Eintrag im Feld "Ausführen auf Clusternode" werden im Cluster nicht eingeplant; Knotenstatus in Aktive Jobs prüfen.

Formulare oder Masken zeigen auf einem Knoten alte Felder

MetaForm-Cache per Aktion auf allen Knoten ungültig machen.

Start bricht mit

The values in the "State" column:

State	Meaning
CURRENT	The node whose mask is currently displayed.
RESPONDING	Configured node whose last status message is not older than 180 seconds.
STALE	The last status message is older than 180 seconds (possible causes: node failed, heartbeat switched off or replication interrupted).
MISSING	The node is listed in PoOptions.clusterNodes, but no status message is available: the node has never reported (not started, different name, replication does not work) or its last message has expired (status messages are removed from the cache after 300 seconds, so a failed node changes from STALE to MISSING).
OBSERVED_ONLY	The node sends status but is not listed in PoOptions.clusterNodes (e.g. spelling of the name or a missing entry).

Typical symptoms and checks

"Session-Mode" im Clusterstatus prüfen. Bei Spring Session: gleiche Redis-Verbindung auf allen Knoten Veraltete Daten nach Änderungen auf einem anderen Knoten

Symptom	Check
The entry "ClusterNode1" or a node stays on MISSING although all nodes are running	PoOptions.clusterNodes still contains the default value, or names that differ from PoOptions.clusterNode. Compare the names on all nodes and in the list.
Other nodes are not visible (MISSING/STALE), topology shows "None"	isDistributed=true on all nodes and restarted? With RMI: same multicast group and port, multicast allowed in the network, suitable timeToLive. With JMS: broker reachable, credentials valid, useJmsReplication=true on all nodes. Check the replication peers in the "List of caches" mask.
A change to a job or system parameter takes effect on one node only	The forwarding runs via the cache replication. Check the cluster status and the replication peers; replicatePuts must not be set to false.
A job runs on no node	Triggers without an entry in the field "Run on cluster node" are not scheduled in the cluster; check the node status in Active Jobs.
Forms or masks show old fields on one node	Invalidate the MetaForm cache on all nodes using the action.
Startup aborts with "Unsafe Redis maxmemory-policy ..." ab	Set Redis auf to maxmemory-policy noeviction stellen (nur bei only with redis-caffeine).
Start bricht ab Startup aborts: "Unsupported value ... webdesk.hibernate.cache.provider"	Erlaubt sind Permitted values are ehcache2, redis-caffeine, disabled.
Nach dem Wechsel zu einem anderen Knoten erscheint die Anmeldeseite	The login page appears after switching to another node	Check the "Session mode" in the cluster status. With Spring Session: same Redis connection on all nodes, redis.session.cookie.jvmRoute passend zur Route des Load Balancers (Warnung im Log, wenn keine Route gefunden wird).	matching the route of the load balancer (a warning is logged if no route is found).
Outdated data after changes on another node (redis-caffeine)	Kennzahlen zu Publish-, Apply- und Verbindungsfehlern prüfen; gegebenenfalls Region in excludedMutableRegions aufnehmen.

Checkliste für die Inbetriebnahme

Pro Knoten einen eindeutigen PoOptions.clusterNode festlegen (WfStartup.engineName bleibt im Normalfall auf dem Standard), isDistributed=true und – falls gewünscht – useJmsReplication=true mit Broker-Zugang setzen.

Netzwerk prüfen: bei RMI Multicast (Standard

Check the metrics for publish, apply and connection errors; if necessary, add the region to excludedMutableRegions.

Commissioning checklist

1. Define a unique PoOptions.clusterNode per node (WfStartup.engineName normally stays at the default), set isDistributed=true and, if desired, useJmsReplication=true with the broker account.
2. Check the network: with RMI, multicast (default 230.0.0.1:4446) zwischen den Knoten, bei JMS Zugriff auf den Broker, außerdem Zugriff aller Knoten auf Redis. Redis-Verbindung between the nodes; with JMS, access to the broker; in addition, access of all nodes to Redis.
3. Set the Redis connection (redis.connection.url oder or redis.clusterNodes) auf allen Knoten setzen; Passwort nur aus einer geschützten Quelle. Entscheiden, welche Session-Art verwendet wird on all nodes; take the password only from a protected source.
4. Decide which session type is used (redis.useAsSessionStore oder Tomcat-Session-Manager) und Route des Load Balancers abstimmen or Tomcat session manager) and coordinate the route of the load balancer (redis.session.cookie.jvmRoute).
5. Hibernate-Anbieter einheitlich festlegen Define the Hibernate provider uniformly (webdesk.hibernate.cache.provider); bei with redis-caffeine, take the Redis -Richtlinie noeviction und das Löschen der Schlüssel policy noeviction and the deletion of the keys wd:hibernate:l2:* berücksichtigen. Knoten starten into account.
6. Start the nodes; in der Maske the "Systemparameter" die Liste System parameters" mask, fill the list PoOptions.clusterNodes mit allen Knotennamen füllen.
7. In der Maske "Clusterstatus" prüfen: alle Knoten RESPONDING bzw. CURRENT, Topologie wie geplant, einheitliche Versionen.
8. Jobs: für jeden Trigger den Knoten im Feld "Ausführen auf Clusternode" festlegen und in "Aktive Jobs" kontrollieren with all node names.
9. Check in the "Cluster Status" mask: all nodes RESPONDING or CURRENT, topology as planned, uniform versions.
10. Jobs: define the node in the field "Run on cluster node" for every trigger and check it in "Active Jobs".