Vergleichsreport

The file webdesk.properties is the startup configuration of Webdesk 4. 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_...). 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 of the Webdesk application in the servlet container (Windows installer: <Webdesk-Webapp>\WEB-INF\classes\webdesk.properties).
• 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.
• Webdesk does not start without this file (error "Error while trying to load webdesk.properties"), unless the embedded database is enabled (see webdesk.useEmbeddedDatabase). 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). 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

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 and webdesk.encryption.key.source (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 are renamed to webdesk.connection.* and webdesk.dialect (provided the new key does not exist yet).
• webdesk-SessionFactory.executeIndexManager is renamed to PoStartup.executeIndexManager.
• The driver com.mysql.jdbc.Driver is replaced by org.mariadb.jdbc.Driver (the MySQL driver is not shipped).
• For JDBC URLs starting with jdbc:mysql, the parameters permitMysqlScheme and allowMultiQueries=true are added.
• For SQL Server JDBC URLs (jdbc:sqlserver) without an encrypt parameter, ;encrypt=false is appended; the dialect org.hibernate.dialect.SQLServerDialect becomes org.hibernate.dialect.SQLServer2012Dialect.
• Obsolete cache replication entries are removed or renamed (webdesk.cacheReplication.peerProvider.properties becomes webdesk.cacheReplication.RMI.peerProvider.properties).

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).

Database connection

Encryption of the credentials

Webdesk encrypts the credentials in webdesk.properties with a key (AES-256). 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). For more about the change of the encryption see New Features in 4.56.

Warning: If the key is lost, the encrypted credentials in webdesk.properties 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) 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.

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 and remove the entry webdesk.encryption.key.
4. Restart Webdesk and verify that the system starts.
5. 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 is missing on a node, it reads the key from the database (PoFile, FILE_UID = 'encryptionKey'); 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) be removed with DELETE FROM PoFile WHERE FILE_UID='encryptionKey';, but only after all nodes have started successfully with enc.key. For further cluster settings see the page "Cluster- und Cache-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 itself and lets you choose between "Basic" and "Expert" mode. Direct call:

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

• Without path, the webdesk.properties in the current working directory is used.
• The parameters webdeskLogin, webdeskPassword, sharkLogin, sharkPassword 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 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 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 connector (IF6020)

Example with two connectors:

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

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-address>
PoHelpOptions.errorReportEnabled = true

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 and SecurityHeadersOptions.forceSameSiteNoneCookieAttribute; 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 -Dkey=value (e.g. in CATALINA_OPTS / JAVA_OPTS)
3. Value in webdesk.properties

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 becomes WD_WEBDESK_CONNECTION_DRIVER_CLASS
• webdesk.ta.if6020impl.rmi becomes WD_WEBDESK_TA_IF6020IMPL_RMI
• PoOptions.clusterNode becomes WD_POOPTIONS_CLUSTERNODE

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

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 has no value:

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

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

Note: If you want to use encrypted credentials in the container, set webdesk.credentials.encrypted = true in the file and supply in the variables the Base64 values encrypted with the system key. Because WD_WEBDESK_EXITJVMONCONNECTIONERROR does not reach the check (see table), enter webdesk.exitJvmOnConnectionError = true in 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".

Troubleshooting

• Webdesk does not start, "Error while trying to load webdesk.properties": the file is missing on the classpath (WEB-INF/classes).
• Startup aborts with "... in webdesk.properties has no value": the credentials are not in the file, but webdesk.credentials.encrypted 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 or webdesk.encryption.key) does 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 and webdesk.luceneIndexing determine which checks run at startup.