To start with your own configuration, clone the community branch to /etc/openxpki and read QUICKSTART.md.

git clone https://github.com/openxpki/openxpki-config.git --branch=community /etc/openxpki

This repository holds a boilerplate configuration for OpenXPKI which must be installed to /etc/openxpki/.

The upstream repository provides three branches:

Credentials and, if used, the local user database are kept in the folder /etc/openxpk/local. Those files will contain passwords in plain text and items like hostnames which will likely depend on the actual environment so we do not recommend to add them to the repository but deploy those on the machines manually or by using a provisioning system.

The files are already linked into the configuration layer and must be created before the system can be used. Templates for those files are provided in contrib/local, copy the directory cp -a /etc/openxpki/contrib/local /etc/openxpki and adjust the files as needed.

Add your realms in config.d/system/realms.yaml and setup the routing for the webui in the realm section of client.d/service/webui/default.yaml.

For each realm, create a corresponding directory in config.d/realm/, for a test drive you can just add a symlink to realm.tpl, for a production setup we recommend to create a directory and add the basic artefacts as follows:

mkdir workflow workflow/def profile notification
ln -s ../../realm.tpl/api/
ln -s ../../realm.tpl/auth/
ln -s ../../realm.tpl/crl/
ln -s ../../realm.tpl/crypto.yaml
ln -s ../../realm.tpl/uicontrol/
cp ../../realm.tpl/profile/default.yaml profile/
ln -s ../../../realm.tpl/profile/template/ profile/
cp ../../realm.tpl/notification/smtp.yaml.sample notification/smtp.yaml
ln -s ../../../realm.tpl/workflow/global workflow/
ln -s ../../../realm.tpl/workflow/persister.yaml workflow/
(cd workflow/def/ && find ../../../../realm.tpl/workflow/def/ -type f | xargs -L1 ln -s)
# In most cases you do not need all workflows and we recommend to remove them
# those items are rarely used
cd workflow/def
rm certificate_export.yaml certificate_revoke_by_entity.yaml report_list.yaml
# if you dont plan to use EST remove those too
rm est_*
# same for SCEP
rm scep_*

We recommend to add the "vanilla" files to the repository immediately after copy and before you do any changes:

git -C /etc/openxpki add config.d/
git commit -m "Initial commit with Realms"

The default configuration has a static HTML page set as the home for the User role. The code for this page must be manually placed to /var/www/static/<realm>/home.html, an example can be found in the contrib directory. If you don't want a static page, remove the welcome and home items from the uicontrol/_default.yaml. If you want to use the same pages for all realms, put them into a folder named _global.

To issue certificates you need to define the profiles first. Adjust your realm wide CDP/AIA settings, validity and key parameters in profile/default.yaml.

For each profile you want to have in this realm, create a file with the profile name. You can find templates for most use cases in realm.tpl/profile, there is also a sample.yaml which provides an almost complete reference.

We recommend to have global settings, for most of the extensions, in the default.yaml and only put the subject composition and the key usage attributes in the profile file. It is advised to NOT link those files but create real copies to ease updates from the upstream repository and avoid any accidential changes to the used profiles.

The folder contrib/i18n/ contains the translation files from the upstream project. If you need local extensions or want to change individual translations, create a file named openxpki.po.local and make your changes here - never touch the openxpki.po file itself.

You can find a Makefile in the main folder, that can be used to create the required compiled files. Running make mofiles creates the openxpki.mo files in the language directories, make install deploys them to the system. Note: it is required to restart the openxpki client daemon to make the changes visible.

The WebUI status page can show information to identify the running config. The Makefile contains a target make version which will append the current commit hash to the file config.d/system/version.yaml which will make the commit hash visible on the status page.

The config.d folder and the credential files in local should be readable by the openxpki user only as they might contain confidential data.

The files for the protocol wrappers (webui, scep, rpc, est, soap ) must be readable by the webserver, if you add credentials here make sure to reduce the permissions as far as possible.

Starting with v3.32 the client wrappers are handled by a new service layer, it runs under its own user openxpkiclient and reads all configuration from client.d.

By default, the package name for the configuration packages is 'openxpki-config', this can be customized via the file .customerinfo. The format of this file is KEY=VALUE.

PKGNAME=openxpki-config-acme
PKGDESC="OpenXPKI configuration for Acme Corporation"