1Overview
2========
3
4Main configuration
5------------------
6The configuration of OpenXPKI consists of two, fundamental different, parts. There is one global system configuration, which holds information about database, filesystem, etc. where the system lives. The second part are the realm configurations, which define the properties of the certificates within the realm. Each pki realm has its own, independant configuration and is isolated from other realm, so you can run instances with different behaviour with one single OpenXPKI server.
7
8We ship the software with a set of YaML files, and we recommend to keep the given layout. The following documentation uses some notations you should know about.
9
10#. Configuration items are read as a path, which is denoted as a string with the path elements seperated by a dot, e.g. ``system.database.main.type``.
11
12#. The path is assembled from the directory, the name of the configuration file, the path of the element in the YaML notation. The value from the example above can be found in the directory ``system``, file ``database.yaml``, section ``main``, key ``type``.
13
14#. All paths except those starting with *system* or *realm* refer to the configuration of a particular realm. The root node for building the path is the realm's directory found at ``realm/<name of the realm>``.
15
16Config versioning
17-----------------
18
19This idea was dropped, configuration is now read freshly from the filesystem at every restart of the daemon.
20
21Activiate the new configuration
22^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
23
24To activate a new config without a restart, you need to do a reload::
25
26     openxpkictl reload
27
28You can also just send a ``SIGHUP`` to the main process or restart the dameon.
29
30**IMPORTANT**
31
32Those parts of the system are preloaded on server init and need a restart to load a new configuration.
33
34* worflow configuration
35
36* authentication handlers
37
38* database settings
39
40* daemon settings (**never** change anything below `system.server` while the dameon is running as you might screw up your system!)
41
42
43Config Caching and Signing
44--------------------------
45
46Instead of reading the config from the filesystem freshly on each startup,
47there is an option to serialize the config tree into a blob which offers
48the option to use PKCS7 signatures to verify the configuration.
49
50Transform config tree into blob
51^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
52
53Use ``openxpkiadm buildconfig --config path/to/config.d`` to generate the
54blob. The default target is a file ``config.oxi`` in the current directory,
55you specify and alternate location with ``--target myconfig.blob``.
56
57To sign the config blob, you need to add ``--key`` and ``--cert`` pointing
58to the PEM encoded key/certificate files. Its good practice to also add the
59chain certificates to verify the signer up to the root, use ``--chain`` to
60point to a file holding the concatenated PEM block of the issuers to be
61added.
62
63Enable config bootstrap
64^^^^^^^^^^^^^^^^^^^^^^^
65You need to create a node named ``bootstrap`` on the top level of the
66configuraion and should remove any other config items. The easiest way
67to achieve this is to wipe anything from ``/usr/local/etc/openxpki/config.d/``
68and place a file called bootstrap.yaml here::
69
70    # this is the only mandatory option
71    LOCATION: /home/pkiadm/config.oxi
72
73    # This is the default and should be left empty unless overridden
74    # class: OpenXPKI::Config::Loader
75
76    # if you want to use signed configs, set ONE of the ca* options
77    # Path holding the certificates as files (filemame = hash)
78    # ca_certificate_path: /usr/local/etc/openxpki/ca/config.certs/
79    # All certificates in one file
80    # ca_certificate_file: /usr/local/etc/openxpki/ca/config.pem
81
82    # temp dir, required to create files to perform signature verification
83    # tmpdir: /tmp
84
85    # path to openssl
86    # openssl: /usr/bin/openssl
87
88Configure signature verification
89^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
90
91Signature is validated using ``openssl smime -verify``. If you have placed
92the chain certificates into the config blob, it is sufficient to have the
93root certificates here, if not, make sure you have all certificates here
94to create the full chain. Directory needs to hold the certificates in the
95well-known openssl hashed filename format, the single file must hold the
96concatenated PEM blocks.
97
98Note: Currently we do not make any checks on the certificate itself so any
99certificate from the given roots/chains can be used for signing so it is
100recommended to setup a dedicated CA for the config signature. We are working
101on making the signer authorization pattern used in other parts of the system
102available for config signatures with one of the next releases.
103
104
105Logging
106-------
107
108OpenXPKI uses Log4perl as its primary system log. Logging during startup and in critical situations is done via STDERR.
109