Vergleichsreport

Die Datei The file webdesk.properties ist die Startkonfiguration von is the startup configuration of Webdesk 4. Sie enthält die Verbindungsdaten zur Webdesk- und zur Shark-Datenbank, die Einstellungen zur Verschlüsselung dieser Zugangsdaten und einige Schalter, die das Verhalten beim Start des Systems steuern. Diese Seite richtet sich an Systemadministratoren und Berater, die ein System installieren, auf Container umstellen oder Startprobleme analysieren. Fachliche Einstellungen (Mandanten, Jobs, Berechtigungen usw.) werden nicht hier, sondern in der Anwendung vorgenommen, siehe z. B. Systemparameter Portal & Organisation. Ausgewählte Schlüssel der Datei können zusätzlich über JVM-Parameter (-Dschlüssel=wert) oder Umgebungsvariablen It contains the connection data for the Webdesk and Shark databases, the settings for encrypting these credentials and a few switches that control how the system behaves at startup. This page is intended for system administrators and consultants who install a system, move it to containers or analyze startup problems. Functional settings (clients, jobs, authorizations, etc.) are not made here but in the application itself, see e.g. System parameters Portal & Organization.

Selected keys of the file can additionally be overridden by JVM parameters (-Dkey=value) or environment variables (WD_...) übersteuert werden. Das ist die empfohlene Methode für Container-Betrieb, weil dann keine Zugangsdaten in der Datei stehen müssen.

Ablageort und Aufbau

. This is the recommended method for container operation, because then no credentials need to be stored in the file.

Location and structure

• Webdesk looks for the file on the classpath of the web application. In a standard installation it is therefore located at WEB-INF/classes/webdesk.properties der Webdesk-Anwendung im Servlet-Container (Windows-Installer of the Webdesk application in the servlet container (Windows installer: <Webdesk-Webapp>\WEB-INF\classes\webdesk.properties).
• Die Datei ist eine Java-Properties-Datei: eine Zeile pro Eintrag in der Form schlüssel = wert, Kommentarzeilen beginnen mit #. Die Datei wird beim Start gelesen, Änderungen werden erst nach einem Neustart wirksam.
• Als Ausgangspunkt dienen die vom Installer ausgelieferte Datei bzw. die Vorlage webdesk.properties.template der Webanwendung. Kundenbeispiele finden sich im Quellcode unter The file is a Java properties file: one entry per line in the form key = value; comment lines start with #. The file is read at startup; changes only take effect after a restart.
• Use the file shipped with the installer or the template webdesk.properties.template of the web application as a starting point. Customer examples can be found in the source code under webdesk-webapp/src/test/resources/customerprops.
• Ohne diese Datei startet Webdesk nicht (Fehler „Error Webdesk does not start without this file (error "Error while trying to load webdesk.properties“), außer es ist die eingebettete Datenbank aktiviert (siehe properties"), unless the embedded database is enabled (see webdesk.useEmbeddedDatabase). Auch beim Betrieb mit Umgebungsvariablen muss daher mindestens eine kleine Datei vorhanden sein. Webdesk schreibt beim Start selbst in die Datei (Verschlüsselung der Zugangsdaten, Schlüssel, Anpassung veralteter Einträge, Zurücksetzen von Even when operating with environment variables, at least a small file must therefore exist.
• Webdesk itself writes to the file at startup (encrypting the credentials, the key, adjusting outdated entries, resetting webdesk.runRegistration). Der Benutzer, unter dem der Container läuft, benötigt daher Schreibrechte, und die Datei muss bei Container-Betrieb auf einem dauerhaften Speicher liegen. Vor manuellen Änderungen ist eine Sicherung anzulegen.

Minimales Beispiel

• The user running the container therefore needs write permission, and in container operation the file must reside on persistent storage. Create a backup before making manual changes.

Minimal example

webdesk.runRegistration = 1

webdesk.connection.driver_class = org.mariadb.jdbc.Driver
webdesk.connection.url = jdbc:mysql://<db-host>/webdesk
webdesk.dialect = org.hibernate.dialect.MySQLDialect
webdesk.connection.username = <db-user>
webdesk.connection.password = <db-password>

shark.connection.driver_class = org.mariadb.jdbc.Driver
shark.connection.url = jdbc:mysql://<db-host>/shark
shark.connection.username = <db-user>
shark.connection.password = <db-password>

webdesk.ta.if6020impl.rmi = rmi://<ta-host>:4009/taRmiBroker

Beim ersten Start verschlüsselt Webdesk die Benutzernamen und Passwörter in der Datei, erzeugt (bzw. liest) den Verschlüsselungsschlüssel und trägt At the first start Webdesk encrypts the user names and passwords in the file, generates (or reads) the encryption key and itself adds webdesk.credentials.encrypted, shark.credentials.encrypted, webdesk.encryption.key und and webdesk.encryption.key.source selbst ein (siehe „Verschlüsselung der Zugangsdaten“).

Automatische Anpassungen beim Start

Webdesk korrigiert beim Start folgende veraltete Einträge in der Datei und speichert sie danach neu:

(see "Encryption of the credentials").

Automatic adjustments at startup

At startup Webdesk corrects the following outdated entries in the file and then saves it again:

• The old keys hibernate.connection.driver_class, hibernate.connection.url, hibernate.connection.username, hibernate.connection.password, hibernate.dialect werden in are renamed to webdesk.connection.* bzw. and webdesk.dialect umbenannt (sofern der neue Schlüssel noch nicht existiert (provided the new key does not exist yet).
• webdesk-SessionFactory.executeIndexManager wird in is renamed to PoStartup.executeIndexManager umbenannt.
• Der Treiber The driver com.mysql.jdbc.Driver wird durch is replaced by org.mariadb.jdbc.Driver ersetzt (der MySQL-Treiber wird nicht mitgeliefertthe MySQL driver is not shipped).
• Bei For JDBC - URLs , die mit starting with jdbc:mysql beginnen, werden die Parameter permitMysqlScheme und the parameters permitMysqlScheme and allowMultiQueries=true ergänzt. Bei JDBC-URLs für SQL Server are added.
• For SQL Server JDBC URLs (jdbc:sqlserver) ohne Parameter encrypt wird without an encrypt parameter, ;encrypt=false angehängt; der Dialekt is appended; the dialect org.hibernate.dialect.SQLServerDialect wird zu becomes org.hibernate.dialect.SQLServer2012Dialect.
• Veraltete Cache-Replikations-Einträge werden entfernt bzw. umbenannt Obsolete cache replication entries are removed or renamed (webdesk.cacheReplication.peerProvider.properties wird zu becomes webdesk.cacheReplication.RMI.peerProvider.properties).

Hinweis: Diese Korrekturen betreffen nur die Datei. Werte, die per Umgebungsvariable oder JVM-Parameter geliefert werden, werden nicht korrigiert und müssen bereits die aktuelle Schreibweise haben (z. B. den Treiber Note: These corrections only affect the file. Values supplied by environment variables or JVM parameters are not corrected and must already use the current notation (e.g. the driver org.mariadb.jdbc.Driver).

Datenbankverbindung

Eigenschaft

Erklärung

Database connection

Verschlüsselung der Zugangsdaten

Encryption of the credentials

Webdesk encrypts the credentials in webdesk.properties mit einem Schlüssel with a key (AES-256). Derselbe Schlüssel wird auch für andere in der Anwendung gespeicherte Passwörter verwendet, etwa in Konnektoren (Datenbank-, REST-, Notes-Konnektor), der Dokumentenverwaltung (Repositories) und im Groupware-Zugriff The same key is also used for other passwords stored in the application, for example in connectors (database, REST and Notes connectors), the document management (repositories) and the groupware access (Graph/Exchange). Mehr zur Umstellung der Verschlüsselung finden Sie in Neue For more about the change of the encryption see New Features in 4.56.

Achtung: Geht der Schlüssel verloren, können die verschlüsselten Zugangsdaten Warning: If the key is lost, the encrypted credentials in webdesk.properties und die verschlüsselt gespeicherten Passwörter in der Datenbank nicht mehr entschlüsselt werden. Webdesk kann dann nicht mehr gestartet werden bzw. die Verbindungen funktionieren nicht mehr. Der Schlüssel (enc.key bzw. der Eintrag and the encrypted passwords stored in the database can no longer be decrypted. Webdesk then can no longer be started or the connections stop working. The key (enc.key or the entry webdesk.encryption.key) muss daher unabhängig von der Datenbank-Sicherung separat gesichert werden. Ein Schlüssel, der nur in einer Container-Instanz ohne dauerhaften Speicher liegt, geht beim Austausch des Containers verloren.

Eigenschaft

Erklärung

must therefore be backed up separately, independently of the database backup. A key that exists only in a container instance without persistent storage is lost when the container is replaced.

Schlüssel in eine eigene Datei auslagern

Empfohlen ist, den Schlüssel nach dem ersten erfolgreichen Start aus der Konfigurationsdatei in eine eigene Datei enc.key auszulagern und diese getrennt zu sichern:

Moving the key to a separate file

We recommend moving the key out of the configuration file into a separate file enc.key after the first successful start and backing it up separately:

1. Create a backup of webdesk.properties and of the databases.
2. Write the value of the entry webdesk.encryption.key as the only line into a new file enc.key and place it in the same directory as webdesk.properties.
3. In webdesk.properties set the entry webdesk.encryption.key.source = file setzen und den Eintrag and remove the entry webdesk.encryption.key entfernen.
4. Webdesk neu starten und prüfen, dass das System startet.
5. enc.key getrennt von der Anwendung sichern.

Verhalten im Cluster

1. Restart Webdesk and verify that the system starts.
2. Back up enc.key separately from the application.

Behavior in a cluster

All nodes must work with the same key. If the entry webdesk.encryption.key.source, liest er den Schlüssel aus der Datenbank is missing on a node, it reads the key from the database (PoFile, FILE_UID = 'encryptionKey'); beim Anlegen wird die Tabelle gesperrt, sodass nur ein Schlüssel entsteht. Wird der Schlüssel in enc.key ausgelagert, muss die Datei auf jedem Knoten mit demselben Inhalt vorliegen. Der Datenbankeintrag wird danach nicht mehr verwendet und kann (laut Hinweis in Neue when creating it, the table is locked so that only one key is created. If the key is moved to enc.key, the file must exist with identical content on every node. The database entry is then no longer used and can (according to the note in New Features in 4.56) mit be removed with DELETE FROM PoFile WHERE FILE_UID='encryptionKey'; entfernt werden, erst nachdem alle Knoten erfolgreich mit , but only after all nodes have started successfully with enc.key gestartet sind. Weitere Cluster-Einstellungen siehe Seite „Cluster- . For further cluster settings see the page "Cluster- und Cache-Betrieb“.

Kommandozeilenwerkzeug CredentialsEncryptor

Mit dem Werkzeug webdesk-encryptor lassen sich Zugangsdaten in einer webdesk.properties verschlüsseln, ansehen und neu setzen, ohne das System zu starten. Auf Windows-Installationen liegt dafür im Tomcat-Verzeichnis bin das Skript manageWebdeskDBProps.bat, das die Datei und die Programmdatei Betrieb".

Command line tool CredentialsEncryptor

The tool webdesk-encryptor can encrypt, display and reset credentials in a webdesk.properties without starting the system. On Windows installations the script manageWebdeskDBProps.bat in the Tomcat bin directory is provided for this; it finds the file and the program file webdesk-encryptor-*.jar selbst sucht und zwischen „Basic“- und „Expert“-Modus wählen lässt. Direkter Aufruf itself and lets you choose between "Basic" and "Expert" mode. Direct call:

java -cp webdesk-encryptor-<version>.jar at.workflow.webdesk.tools.CredentialsEncryptor path=<Pfad><path>/webdesk.properties [webdeskLogin=<user>] [webdeskPassword=<pw>] [sharkLogin=<user>] [sharkPassword=<pw>]

• Ohne Without path wird , the webdesk.properties im aktuellen Arbeitsverzeichnis verwendet. Die Parameter in the current working directory is used.
• The parameters webdeskLogin, webdeskPassword, sharkLogin, sharkPassword setzen den jeweiligen Benutzernamen bzw. das Passwort neu (im Klartext angegeben, das Werkzeug verschlüsselt sie). Sind die Zugangsdaten noch nicht verschlüsselt, werden sie verschlüsselt und set the respective user name or password anew (given in plain text, the tool encrypts them).
• If the credentials are not encrypted yet, they are encrypted and webdesk.credentials.encrypted / shark.credentials.encrypted gesetzt; Werte im alten Verschlüsselungsverfahren werden neu verschlüsselt.
• Danach zeigt das Werkzeug ein Menü: Werte entschlüsselt anzeigen, verschlüsselte Werte anzeigen, alle vier Werte neu eingeben, beenden.
• Enthält die Datei noch keine Schlüsselquelle, erzeugt das Werkzeug einen neuen Schlüssel und trägt ihn mit der Quelle webdesk_properties ein. Das Werkzeug unterstützt nur diese Quelle; bei are set; values using the old encryption scheme are re-encrypted.
• Afterwards the tool shows a menu: display values decrypted, display encrypted values, re-enter all four values, quit.
• If the file does not yet contain a key source, the tool generates a new key and enters it with the source webdesk_properties. The tool only supports this source; with webdesk.encryption.key.source = file bricht es mit einer Fehlermeldung ab.

Achtung: Wird das Werkzeug auf eine Datei angewendet, die zu einem bereits laufenden System gehört, aber keinen Schlüssel enthält, entsteht ein neuer, anderer Schlüssel als der im System verwendete. Verwenden Sie das Werkzeug nur mit der Original-Datei des Systems samt Schlüssel.

Startverhalten

Eigenschaft

Erklärung

mögliche Wert(e)

webdesk.runRegistration

• it aborts with an error message.

Warning: If the tool is applied to a file that belongs to an already running system but contains no key, a new key is created that differs from the one used by the system. Use the tool only with the original file of the system including its key.

Startup behavior

TA -Konnektor connector (IF6020)

Example with two connectors:

webdesk.ta.if6020impl.rmi = rmi://<ta-host1>:4009/taRmiBroker;rmi://<ta-host2>:4012/taRmiBroker

Eigenschaften von Beans überschreiben

Jeder Eintrag der Form <beanId>.<eigenschaft> = wert setzt beim Start die Eigenschaft der Spring-Bean mit dieser Id (Bean-Namen und Eigenschaften entsprechen den Namen in der Maske „Systemparameter“, siehe Systemparameter Portal & Organisation). Das ist ein Spring-„PropertyOverrideConfigurer“, der webdesk.properties liest.

Overriding bean properties

Every entry of the form <beanId>.<property> = value sets, at startup, the property of the Spring bean with that id (bean names and properties correspond to the names in the "Systemparameter" mask, see System parameters Portal & Organization). This is a Spring "PropertyOverrideConfigurer" that reads webdesk.properties.

Examples:

PoOptions.clusterNode = node1
PoHelpOptions.serviceDeskEmail = <service-desk-adresse>address>
PoHelpOptions.errorReportEnabled = true

Achtung: Einträge mit unbekannter Bean-Id oder unbekannter Eigenschaft werden ohne Fehlermeldung ignoriert. Ein Tippfehler bleibt daher unbemerkt; prüfen Sie nach dem Neustart in der Anwendung, ob der Wert wirksam ist. Per Umgebungsvariable oder JVM-Parameter können nur die in der Tabelle unten genannten Schlüssel übersteuert werden, darunter Warning: Entries with an unknown bean id or an unknown property are ignored without an error message. A typo therefore goes unnoticed; after the restart, check in the application whether the value is effective. Only the keys listed in the table below can be overridden by environment variable or JVM parameter, including PoOptions.clusterNode, WfStartup.engineName und and SecurityHeadersOptions.forceSameSiteNoneCookieAttribute; alle anderen Bean-Einträge müssen in der Datei stehen.

JVM-Parameter und Umgebungsvariablen

Bestimmte Schlüssel können unabhängig von der Datei übersteuert werden. Für diese Schlüssel gilt die Rangfolge (höchste zuerst):

all other bean entries must be in the file.

JVM parameters and environment variables

Certain keys can be overridden independently of the file. For these keys the following precedence applies (highest first):

1. Environment variable WD_...
2. JVM parameter -Parameter -DschlüsselDkey=wertvalue (ze. Bg. in CATALINA_OPTS / JAVA_OPTS)
3. Wert Value in webdesk.properties

Namensregel

Naming rule

The name of the environment variable is derived from the key name as follows: convert all letters to upper case, replace every dot with an underscore and prepend WD_. Other characters (e.g. underscores) remain unchanged. Examples:

• webdesk.connection.driver_class wird zu becomes WD_WEBDESK_CONNECTION_DRIVER_CLASS
• webdesk.ta.if6020impl.rmi wird zu becomes WD_WEBDESK_TA_IF6020IMPL_RMI
• PoOptions.clusterNode wird zu becomes WD_POOPTIONS_CLUSTERNODE

Eine leere oder nur aus Leerzeichen bestehende Umgebungsvariable wird ignoriert (der Wert aus der Datei gilt dann weiter). Nicht in der Liste enthaltene Schlüssel können nicht per Umgebungsvariable gesetzt werden, auch wenn eine passend benannte Variable existiert.

Überschreibbare Schlüssel

Schlüssel

Umgebungsvariable

Bemerkung

An empty environment variable or one consisting only of whitespace is ignored (the value from the file then continues to apply). Keys that are not in the list cannot be set by environment variable, even if a suitably named variable exists.

Overridable keys

Beispiel für den Container-Betrieb

Example for container operation

In the file webdesk.properties inside the container, one entry is enough that states that the credentials supplied via the environment are not encrypted (this entry cannot be set by environment variable). Without it, Webdesk tries at startup to encrypt the (missing) values of the file and aborts with the message that webdesk.connection.username in webdesk.properties keinen Wert hat has no value:

webdesk.credentials.encrypted = false
webdesk.runRegistration = 1

Die Umgebungsvariablen (hier als Liste, wie in einer Docker-Compose-Datei The environment variables (shown as a list, as in a Docker Compose file):

WD_WEBDESK_CONNECTION_DRIVER_CLASS=org.mariadb.jdbc.Driver
WD_WEBDESK_CONNECTION_URL=jdbc:mysql://<db-host>/webdesk?permitMysqlScheme&allowMultiQueries=true
WD_WEBDESK_CONNECTION_USERNAME=<db-user>
WD_WEBDESK_CONNECTION_PASSWORD=<db-password>
WD_WEBDESK_DIALECT=org.hibernate.dialect.MySQLDialect
WD_SHARK_CONNECTION_DRIVER_CLASS=org.mariadb.jdbc.Driver
WD_SHARK_CONNECTION_URL=jdbc:mysql://<db-host>/shark?permitMysqlScheme&allowMultiQueries=true
WD_SHARK_CONNECTION_USERNAME=<db-user>
WD_SHARK_CONNECTION_PASSWORD=<db-password>
WD_WEBDESK_TA_IF6020IMPL_RMI=rmi://<ta-host>:4009/taRmiBroker
WD_WEBDESK_EXITJVMONCONNECTIONERROR=true

Hinweis: Möchten Sie im Container verschlüsselte Zugangsdaten verwenden, setzen Sie Note: If you want to use encrypted credentials in the container, set webdesk.credentials.encrypted = true in der Datei und liefern in den Variablen die mit dem Systemschlüssel verschlüsselten Base64-Werte. Da the file and supply in the variables the Base64 values encrypted with the system key. Because WD_WEBDESK_EXITJVMONCONNECTIONERROR die Prüfung nicht erreicht (siehe Tabelle), tragen Sie does not reach the check (see table), enter webdesk.exitJvmOnConnectionError = true in der Datei ein, wenn der Container bei Verbindungsfehlern beendet werden soll.

Cluster und Redis (Überblick)

Für den Betrieb mit mehreren Knoten kennt webdesk.properties unter anderem folgende Schlüssel; Bedeutung und Zusammenspiel siehe Seite „Cluster- und Cache-Betrieb“.

Eigenschaft

Erklärung

mögliche Wert(e)

isDistributed

the file if the container is to exit on connection errors.

Cluster and Redis (overview)

For operation with several nodes, webdesk.properties knows, among others, the following keys; for their meaning and interplay see the page "Cluster- und Cache-Betrieb".

Fehlersuche

Troubleshooting

• Webdesk does not start, "Error while trying to load webdesk.properties“: Die Datei fehlt im Klassenpfad properties": the file is missing on the classpath (WEB-INF/classes).
• Start bricht ab mit „Startup aborts with "... in webdesk.properties has no value“: Die Zugangsdaten stehen nicht in der Datei, value": the credentials are not in the file, but webdesk.credentials.encrypted fehlt jedoch (siehe Container-Beispiel). Entschlüsselung schlägt fehl bzw. System startet nicht nach Wechsel der Datei oder des Servers: Schlüssel is missing (see the container example).
• Decryption fails or the system does not start after replacing the file or the server: the key (enc.key bzw. or webdesk.encryption.key) stimmt nicht mit dem im System verwendeten Schlüssel überein.
• Eine Umgebungsvariable zeigt keine Wirkung: Schlüssel in der Tabelle „Überschreibbare Schlüssel“ prüfen, Namensregel prüfen (Punkte werden zu Unterstrichen, Großbuchstaben), Variable darf nicht leer sein.
• Änderung in der Datei wirkt nicht oder ist nach dem Start verschwunden: Die Datei wird nur beim Start gelesen; Webdesk schreibt sie dabei teilweise neu (siehe „Automatische Anpassungen beim Start“) und setzt webdesk.runRegistration = 1 nach der Registrierung auf 0.
• Start ist sehr langsamdoes not match the key used by the system.
• An environment variable has no effect: check the key in the table "Overridable keys" and the naming rule (dots become underscores, upper case); the variable must not be empty.
• A change in the file has no effect or has disappeared after startup: the file is only read at startup; Webdesk partly rewrites it (see "Automatic adjustments at startup") and sets webdesk.runRegistration = 1 to 0 after the registration.
• Startup is very slow: PoStartup.executeIndexManager, webdesk.disableTimeLineChecks, webdesk-sessionFactory.schemaUpdate, webdesk.runRegistration und and webdesk.luceneIndexing bestimmen, welche Prüfungen beim Start laufen determine which checks run at startup.