Backend

Configuration System

The configuration is organized in YAML files split into areas:

config.d/system/ — system-wide settings (database, crypto, realm definitions)
config.d/realm.tpl/ — realm templates folder, hidden by the config layer
config.d/realm/<name>/ — realm-specific configuration

Configuration paths use dot notation, e.g. system.database.main.type refers to the file config.d/system/database.yaml, key main.type.

Database Connection

OpenXPKI uses a relational database to store certificates, workflows, sessions, and audit logs. Connection parameters are configured in config.d/system/database.yaml.

Supported Databases

Driver	Module	Notes
`MariaDB2`	`libdbd-mariadb-perl`	Recommended for new installations
`MariaDB`	`libdbd-mysql-perl`	Deprecated, will be removed in a future release
`PostgreSQL`	`libdbd-pg-perl`	Fully supported

Note: Driver names are case-sensitive.

Connection Parameters (`config.d/system/database.yaml`)

main:
    debug: 0
    type: MariaDB2
    name: openxpki
    #host: localhost
    #port: 3306
    user: openxpki
    passwd: openxpki

Without a host entry, a local Unix socket connection is used.

Database Schema

The schema files are in contrib/sql/:

# MariaDB/MySQL
mysql -u root --password --database openxpki < contrib/sql/mariadb-backend-schema.sql
mysql -u root --password --database openxpki < contrib/sql/mariadb-frontend-schema.sql

# PostgreSQL
psql -U postgres openxpki < contrib/sql/postgresql-backend-schema.sql
psql -U postgres openxpki < contrib/sql/postgresql-frontend-schema.sql

System Logging

OpenXPKI uses Log4perl for logging. The configuration file is /etc/openxpki/log.conf (path configured in config.d/system/server.yaml under log4perl).

Log Categories (Facilities)

Facility	Logger path	Default level	Description
`AUTH`	`openxpki.auth`	INFO	Logins, logouts, authentication results
`AUDIT`	`openxpki.audit`	INFO	Access to private keys and secrets
`SYSTEM`	`openxpki.system`	WARN	Internal system events
`WORKFLOW`	`openxpki.workflow`	WARN	Internal workflow engine events
`APPLICATION`	`openxpki.application`	INFO	Workflow actions, certificate operations
`DEPRECATED`	`openxpki.deprecated`	WARN	Calls to deprecated code paths
Connector	`connector`	ERROR	Configuration layer / publication targets
Root	(all others)	ERROR	Catch-all for unassigned loggers

Special Appender Types

OpenXPKI comes with two special appenders which serve a special purpose and must not be used outside the intended scope.

OpenXPKI::Server::Log::Appender::Database is used to write the workflow technical log, it must bind to the APPLICATION target and should not log levels higher than INFO.

OpenXPKI::Server::Log::Appender::Audit writes the audit track into the database, it must bind to the AUDIT target. The audit log statements send key/value pairs after the message compatible with the warp_message = 0 configuration as used in Log::Log4perl::Layout::JSON. The given default configuration creates items in the audit table as JSON messages.

log4perl.appender.AuditDBI = OpenXPKI::Server::Log::Appender::Audit
log4perl.appender.AuditDBI.warp_message = 0
log4perl.appender.AuditDBI.layout = Log::Log4perl::Layout::JSON
log4perl.appender.AuditDBI.layout.field.message = %m{chomp}

Changing the Log Level

To raise the log level for debugging, adjust the desired facility in log.conf:

# Workflow debugging
log4perl.category.openxpki.workflow = DEBUG, Logfile

# Full tracing (outputs unencrypted payload data!)
log4perl.category.openxpki.application = TRACE, ApplicationFile, ApplicationDBI

Warning: TRACE level outputs unencrypted communication data and should only be activated briefly during debugging.

After changes to log.conf, it is required to restart the server backend systemctl restart openxpki-serverd

Logrotate

A logrotate configuration is included with the Debian package. The important combination is recreate: 1 in log.conf together with delaycompress in the logrotate configuration.