Operations guide

This document describes the different operation criterias to consider when running PhenixID Signing Workflow.

Audience

System administrators

Backup

Make sure to backup:

- The entire signingworkflow folder, log files may be excluded.

- If the fileDirectory parameter points to an external folder, that folder must be backed up.

- The workflow SQL database

Logs

The table below describes the Java system properties that are required for logging. The provided start script defines valid defaults for these properties.

Name Description
log4j.configurationFile
Must point to the file $WORKFLOW_HOME/config/log4j2.xml
vertx.logger-delegate-factory-class-name
Must have the value io.vertx.core.logging.Log4j2LogDelegateFactory
hazelcast.logging.type
Must have the value log4j2
java.util.logging.config.file Must point to the file $WORKFLOW_HOME/config/logging.properties

Log target files are defined in the log4j configuration file. The log4j configuration is reloaded by the system every 30 seconds. Changes will thus take effect without restarting the server.

The files in the table below are configured by default:

File name Description
server.log Application log for debugging and error detection.
network.log HTTP request logging, disabled by default. TCP logging, disabled by default
db.log Database driver logging, disabled by default.

Application log

This log is used for debugging and error detection. There are three relevant log levels:

INFO Normal operation, mainly start up messages, warnings and errors. Disregards expected failures, like invalid input, accessing non-existent or forbidden resources etc. No request level logging.
DEBUG Logs expected failures, e.g. SAML ticket validation failure. Some configuration logging. Some request level logging.
TRACE Detailed request level and application behaviour logging.

Network log

Network activity log at HTTP and/or TCP level.

Activate HTTP logging by setting log level INFO or higher on the logger io.vertx.ext.web.handler. This will log all incoming http requests.

Activating TCP logging involves several steps:

  1. Set the configuration parameter "logNetworkActivity": true 
  2. Restart the server.
  3. Set log level INFO or higher on the logger io.netty.handler.logging

Activating logNetworkActivity will increase the load on the system, even though the log level is set low and no actual log records are written to file. Do not use this setting except for debug sessions. Restart the server again after deactivating logNetworkActivity.

Database driver log

Log output from the third-party database driver. The driver uses a different logging framework than the rest of the system. Activating its logging thus involves several steps:

  1. Open logging.properties, set log level FINE or higher: com.microsoft.sqlserver.jdbc.level=FINE
  2. Restart the server.
  3. Open log4j2.xml and set log level DEBUG or higher on the logger com.microsoft.sqlserver.jdbc

The setting in logging.properties will ensure that log entries are created in memory, but the entries will not be written to the log file until the log4j logger has level DEBUG or higher. Activating the logger in logging.properties will increase the load on the system, even though the log4j level is set low and no actual log records are written to file. Do not use this setting except for debug sessions. Restart the server again after resetting the log level in logging.properties.

Cluster

ToBeDefined

  • The fileDirectory parameter must point to a drive shared by all the nodes in the cluster

Database tables

ToBeDefined