1# OpenXPKI Configuration Repository 2 3**Note**: Some of the items and features mentioned in this document are only accessible using the enterprise configuration which requires a support subscription. 4 5## TL;DR 6 7To start with your own configuration, clone the `community` branch to `/usr/local/etc/openxpki` and read QUICKSTART.md. 8 9 git clone https://github.com/openxpki/openxpki-config.git --branch=community /usr/local/etc/openxpki 10 11## How to Start 12 13This repository holds a boilerplate configuration for OpenXPKI which must be installed to `/usr/local/etc/openxpki/`. 14 15The upstream repository provides three branches: 16 17| Branch | Description | 18| -------------- | ------------------------------------------------------------ | 19| **master** | An almost empty branch that holds this README | 20| **community** | The recommended branch for running an OpenXPKI Community Edition | 21| **enterprise** | The recommended branch for running an OpenXPKI Enterprise Edition | 22 23### Single Branch Approach 24 25Create your own branch from master and merge the respective branch as a starting point. We recommend to use the string **customer** as branch name and make a single squashed commit. **Please make sure you record the exact commit you start from as you will not be able to merge upstream changes later.** 26 27```bash 28git checkout -b customer 29git merge --squash v3.2 30git commit -m "Initial Checkout based on v3.2" 31``` 32 33In case you want to maintain configuration for different environments as branches we recommend to proceed with the customer branch as a starting point and split into different branches later as described below. 34 35### Credentials / Local Users 36 37Credentials and, if used, the local user database are kept in the folder `/etc/openxpk/local`. Those files will 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. 38 39The 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 /usr/local/etc/openxpki/contrib/local /usr/local/etc/openxpki` and adjust the files as needed. 40 41### Define your Realms 42 43Open `config.d/system/realms.yaml` and add your realms. 44 45For 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: 46 47```bash 48mkdir workflow workflow/def profile notification 49ln -s ../../realm.tpl/api/ 50ln -s ../../realm.tpl/auth/ 51ln -s ../../realm.tpl/crl/ 52ln -s ../../realm.tpl/crypto.yaml 53ln -s ../../realm.tpl/uicontrol/ 54cp ../../realm.tpl/profile/default.yaml profile/ 55ln -s ../../../realm.tpl/profile/template/ profile/ 56cp ../../realm.tpl/notification/smtp.yaml.sample notification/smtp.yaml 57ln -s ../../../realm.tpl/workflow/global workflow/ 58ln -s ../../../realm.tpl/workflow/persister.yaml workflow/ 59(cd workflow/def/ && find ../../../../realm.tpl/workflow/def/ -type f | xargs -L1 ln -s) 60# In most cases you do not need all workflows and we recommend to remove them 61# those items are rarely used 62cd workflow/def 63rm certificate_export.yaml certificate_revoke_by_entity.yaml report_list.yaml 64# if you dont plan to use EST remove those too 65rm est_cacerts.yaml est_csrattrs.yaml 66``` 67 68We recommend to add the "vanilla" files to the repository immediately after copy and before you do **any** changes: 69 70```bash 71git -C /usr/local/etc/openxpki add config.d/ 72git commit -m "Initial commit with Realms" 73``` 74 75#### User Home Page 76 77The 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`. 78 79### Define Profiles 80 81To issue certificates you need to define the profiles first. Adjust your realm wide CDP/AIA settings, validity and key parameters in `profile/default.yaml`. 82 83For 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. 84 85We recommend to have global settings, as most of the extensions, in the `default.yaml` and only put the subject composition and the key usage attributes in the certificate detail file. 86 87### Customize i18n 88 89The 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.local.po and make your changes here - **never touch the openxpki.po file itself**. 90 91You can find a Makefile in the main folder, that can be used to create the required compiled files. Running `make mo` creates the `openxpki.mo` files in the language directories, `make mo-install` deploys them to the system. *Note*: it might be required to restart the webserver to make the changes visible. 92 93## Config Update 94 95There are two strategies to apply enhancements and bug fixes from the upstream repository. 96 97### Direct Merge Strategy 98 99Using `git merge` directly to merge new commits to your customized branch is only recommended if you have not modified your workflows and have only few changes. 100 101You should also review if any relevant changes were made to the files that were copied, e.g. the profiles or the policy files in rpc/est/scep and apply those to your config if required. 102 103### Partial Squash Merge Strategy 104 105The idea behind this approach is to apply all changes from the upstream repository to your local working copy but leave it to the maintainer to bundle them into commits to keep the history small. As the usage of `squash` breaks the history you need to use `cherry-pick` and a temporary branch to prepare the update. 106 107To upgrade the branch `customer` from v3.2 to v3.4 use the following commands: 108 109```bash 110git checkout v3.2 111git merge --squash v3.4 112git commit -m "Upgrade v3.4" 113# write down the hash of the commit created 114git checkout customer 115git cherry-pick <commit> 116``` 117 118This leaves you with the changes applied to the local filesystem, affected files and conflicts can be viewed using `git status`. 119 120* review and resolve conflicts 121 122* review the changes made in `realm.tpl/workflow/global`, those can usually be applied without any problems as long as you did not make any fundamental changes here. 123* review the changes made in `realm.tpl/workflow/def`. If you have modified the default workflows look for any conflicts or possible problems. If you have "forked" away your own workflows by copying them to a realm, check if the changes need to be backported. 124* review the other changes and decide if you want to incorporate them. Look for required changes especially in the service configurations (rpc/est/scep). 125 126Git Cheat Sheet: 127 128```bash 129# show the history of a files changes on the upstream branch 130git log v3.4 -- <filename> 131 132# discard all changes made on a file 133git checkout -- <filename> 134 135# replace file with upstream version 136git checkout v3.4 -- <filename> 137 138# add only some changes for a file 139git reset -- <filename> 140git add -p <filename> 141git checkout -- <filename> 142 143# review changes made to a single file (after the commit was done) 144git show -- <file> 145 146# apply a change from an upstream to a custom file 147git show -- <upstream file> | patch <custom file> 148``` 149 150Make sure you add the exact commit hash from the upstream repository, we recommend to write this into the commit message, e.g.: `git commit -m "Merged upstream changes v3.4"`. 151 152If you have customized i18n files, do not forget to update those after doing the merge. 153 154### Version Tag 155 156The 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. 157 158### File Permissions 159 160The `config.d` folder and the credential files in `local` should be readable by the `openxpki` user only as they might contain confidential data. 161 162The 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. 163 164## Testing 165 166To setup the templates for automated test scripts based on a KeyWordTesting Framework run `make testlib`. This will add a folder `contrib/test/` with sample files and the library classes. 167 168We recommend to not add the `libs` path to the repository but to pull this on each test as the libraries will encapsulate any version dependent behavior. 169 170## Packaging and Customization 171 172By 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. 173 174 PKGNAME=openxpki-config-acme 175 PKGDESC="OpenXPKI configuration for Acme Corporation" 176 177