From a462dd78bb6be498135b4cc22ef75ad2c61bd758 Mon Sep 17 00:00:00 2001 From: Stan Silvert Date: Fri, 26 Aug 2016 16:40:34 -0400 Subject: [PATCH] Update dev doc for keycloak subsystem configuration. --- README.md | 1 + misc/UpdatingServerConfig.md | 65 ++++++++++++++++++++++++++++++++++++ 2 files changed, 66 insertions(+) create mode 100644 misc/UpdatingServerConfig.md diff --git a/README.md b/README.md index c52a172d70..14addf7442 100755 --- a/README.md +++ b/README.md @@ -65,6 +65,7 @@ Contributing * [Testsuite](misc/Testsuite.md) - Details about testsuite, but also how to quickly run Keycloak during development and a few test tools (OTP generation, LDAP server, Mail server) * [Database Testing](misc/DatabaseTesting.md) - How to do testing of Keycloak on different databases * [Updating Database](misc/UpdatingDatabaseSchema.md) - How to change the Keycloak database + * [Changing the Default keycloak-subsystem Configuration](misc/UpdatingServerConfig.md) - How to update the default keycloak-subsystem config * [Developer Mailing List](https://lists.jboss.org/mailman/listinfo/keycloak-dev) - Mailing list to discuss development of Keycloak diff --git a/misc/UpdatingServerConfig.md b/misc/UpdatingServerConfig.md new file mode 100644 index 0000000000..a3282af996 --- /dev/null +++ b/misc/UpdatingServerConfig.md @@ -0,0 +1,65 @@ +# Changing the Default *keycloak-subsystem* Configuration + +If you need to make a change to the default keycloak-subsystem +configuration that is packaged with our distributions, you will need to edit this file: +https://github.com/keycloak/keycloak/blob/master/wildfly/server-subsystem/src/main/config/default-server-subsys-config.properties + +This file contains a single multi-line property containing the subsystem +xml declaration. Maven filtering is used to read this property and +inject it everywhere it needs to go. Editing this file will also take +care of propagating it to the distributions like server-dist and demo-dist. + +Also, you need to create CLI commands for each change by editing this file: +https://github.com/keycloak/keycloak/blob/master/wildfly/server-subsystem/src/main/resources/cli/default-keycloak-subsys-config.cli + +This CLI snippet is used in the scripts required by the overlay distribution. + +## Updating an SPI +The changes you will likely make are when you need to add a new SPI, change an existing SPI, or add/change a provider within an SPI. + +All elements in an SPI declaration are optional, but a full SPI declaration + looks like this: +````xml + + mongo + + + + + + + + + + + + +```` +Here we have two providers defined for the SPI `dblock`. The +`default-provider` is listed as `mongo`. However it is up to the SPI to decide how it will +treat this setting. Some SPIs allow more than one provider and some do not. So +`default-provider` can help the SPI to choose. + +Also notice that each provider defines its own set of configuration +properties. The fact that both providers above have a property called +`lockWaitTimeout` is just a coincidence. + +## Values of type *List* +The type of each property value is interpreted by the provider. However, +there is one exception. Consider the `jpa` provider for the `eventStore` API: +````xml + + + + + + + +```` +We see that the value begins and ends with square brackets. That means that +the value will be passed to the provider as a list. In this example, +the system will pass the +provider a list with two element values `EVENT1` and `EVENT2`. To add +more values to the list, just separate each list element with a comma. Unfortunately, +you do need to escape the quotes surrounding each list element with +`"`.