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