One last revision….
___________________________________________________________________________________ ################################################################################### # README-CONFIG.txt for Fortress Core Configuration Usage # Version 1.0-RC41 # This file contains an overview of the fortress configuration system. ___________________________________________________________________________________ ################################################################################### # SECTION 1. Fortress Configuration Subsystem Overview ################################################################################### Fortress obtains all of its configuration settings from the following two locations: ___________________________________________________________________________________ A. Ant Property files - Seeds downstream fortress.properties, refreshLDAP.xml and slapd.conf files. ___________________________________________________________________________________ The ant property subsystem is fed using three files: i. user.properties - optional, when found, located in user's home directory. Properties found here take precedence over those following. ii. slapd.properties - optional, when found, located in root folder of the package. These props override those found in the build.properties file. iii. build.properties - this file is required and must be located in the root folder of the package. The ant configuration task uses the values found above to seed the fortress.properties and the base ldap load script (refreshLDAPData.xml). It can also be used to populate the slapd.conf (if needing to configure the openldap server to fortress specs). ___________________________________________________________________________________ B. Java System Properties - Optional - Used to override fortress properties at runtime. ___________________________________________________________________________________ These fortress properties may be overridden at runtime by setting as Java System Properties: i. fortress.host ii. fortress.port iii. fortress.admin.user iv. fortress.admin.pw v. fortress.min.admin.conn vi. fortress.max.admin.conn vii. fortress.enable.ldap.ssl viii. fortress.enable.ldap.ssl.debug ix. fortress.trust.store x. fortress.trust.store.password xi. fortress.trust.store.set.prop xii. fortress.config.realm xiii. fortress.ldap.server.type ___________________________________________________________________________________ ################################################################################### # SECTION 2. Fortress Configuration Subsystem Targets ################################################################################### The ant build property files used by the fortress build.xml ant script, pushes attribute values into: A. fortress.properties - primary target. Contains connection coordinates to the remote config node in ldap. B. refreshLDAPData.xml - secondary target. Used to populate an actual ldap config node. C. slapd.conf - this is an optional target - only needed when configuring a new openldap server from scratch. ___________________________________________________________________________________ ################################################################################### # SECTION 3. Precedence of Artifacts found in the Fortress Configuration Subsystem ################################################################################### Fortress uses apache commons configuration system to manage its properties inside its Java runtime environment. This subsystem has been hard wired to pick up properties in the following order: A. fortress.properties file - found on the classpath of that name. B. Java system properties - to override any of the 13 properties listed above. C. LDAP configuration node - found by config coordinates set in the fortress.properties file itself. These properties are mutable inside the fortress config subsystem which allows C's values to override B's to override A's. ___________________________________________________________________________________ ################################################################################### # SECTION 4. More on Fortress properties ################################################################################### The general flow is the fortress.properties provide the coordinates to locate an ldap entry on a remote server. The fortress.properties file is picked off the runtime classpath during startup. Those props are overridden by any of the java system properties. The combination of fortress and system properties are used as coordinates to read the remote server's configuration entry where the remainder of the properties are stored. The remote server node's dn is constructed from fortress.property values: config.realm=DEFAULT config.root=ou=Config,@SUFFIX@ The above would be combined to create the dn: cn=Default, ou=Config, [whatever the @SUFFIX@ is] When reinitialization of properties is needed, to the ldap config node or the DIT itself, re-run this command: # mvn install followed by: A # mvn install -Dload.file=./ldap/setup/refreshLDAPData.xml or B # mvn install -Dload.file=./ldap/setup/ConfigNodeUpdate.xml The A script refreshes the entire LDAP server DIT, which includes deletes of all entries under the suffix, recreating the DIT node structure, and re-adding of the config node. B just updates the configuration node with the new values, preserving all other data. If you need to change an existing ldap system already in use by others, you may modify the values inside the fortress.properties directly, skipping the interim step of updating the ant properties files and re-running mvn install. If the config node must be changed, use any general purpose ldapbrowser to mod its values. Fortress also has config apis to use (ConfigMgr) that add, update and delete configuration entries. Fortress Web will soon have a configuration dialogue page for doing this. More notes: - Use caution when running the -Dload.file target with 'refreshLDAPData.xml' as that script also deletes all nodes the suffix before it reloads anew. - Use the config node update script if you want to update values in the remote configuration without scrubbing data from the DIT. - Don't run refreshLDAPData.xml in production, run ConfigNodeUPdate.xml instead. - There is nothing stopping you from placing all properties inside the fortress.properties file and not the configuration node. - The idea is to minimize the number of locations where the same data must be stored. Imagine a network with hundreds, even thousands of fortress agents running. - We don't need to replicate the same data everywhere which is where remote config nodes are used. - Tailor these procedures to match your requirements. - For more info on which parameters are used where, look at the init-fortress-config target located inside the build.xml file. Shawn
