Grouper configuration in the database and UI

Grouper allows configuration, which is normally in config files, to be stored in the database. This is the preferred approach because:

• Configuration in the database makes the configuration consistent in an environment (otherwise the config files need to be kept in sync for the UI servers, WS servers, daemons, and GSH).

• Editing the configuration in the UI prevents configuration problems and helps users to configure Grouper easier and more reliably.

• It allows the administrator to revert the configuration if needed.

How it works

The grouper.config.hierarchy setting in each config file controls where Grouper reads configuration from, and in what order. To store configuration in the database, the hierarchy ends with database:grouper.

In currently supported Grouper (v4+ and v6+), the default grouper.config.hierarchy in grouper.base.properties already includes database:grouper as the last entry:

database:grouper tells Grouper to check the grouper_config database table for configuration overlays. It must be last so that values edited in the UI override the ones in the properties files. If you have a customized hierarchy, make sure database:grouper is the final entry.

Note: if you have configs you want to differ in different components (e.g. ws/ui/daemon), you need to set those in the config files, and not in the database, which will span all components (e.g. UI/WS/Daemon) that use that database.

Config files

1. grouper.properties

2. grouper-loader.properties

3. subject.properties

4. grouper.client.properties (if there is a grouper.hibernate.properties in the classpath)

5. grouper.cache.properties

6. grouper-ui.properties

7. grouper-ws.properties

8. grouper.text.en.us.properties (v2.5.30+)

Edit the configuration in the UI

There is an editor in the UI

• The source IP address will need to be configured or disabled in grouper-ui.properties:
  
  

  # Restrict the UI configuration editor to these source IP ranges (CIDR), comma separated, # e.g. 1.2.3.4/32, 2.3.4.5/24. Set to 0.0.0.0/0 to allow from everywhere. # If this property is left at its default, only 127.0.0.1/32 (localhost) is allowed. grouperUi.configurationEditor.sourceIpAddresses =

Or put this SQL in the database:

The UI uses comments in the config file to describe the configuration, and will also use configuration metadata (described below).

Import the config

You can import the configuration into the database. You cannot import a "base" config file.

You can import from a config file. This will only be a config file in the classpath or on the filesystem. This is how to get started with this feature. Note, you will need to remove the config from other config files as well, e.g. web service configs.

You can also import from a consolidated export from the filesystem.

Export the config (v2.5.34+)

Open

Config history (v2.5.34+)

Open

Configuration metadata

There can be JSON configuration metadata in the config files to help the UI correctly display and validate the configs. These metadata are in the "base" config files only. This is an example:

Note: just because there is validation doesn't mean a script can't be used... e.g.

Configuration file layout

1. Config file starts with license, which has comments, none of which start with 10 hashes:
   
   

   # # Copyright 2014 Internet2 # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # # Grouper loader uses Grouper Configuration Overlays (documented on wiki) # By default the configuration is read from grouper-loader.base.properties # (which should not be edited), and the grouper-loader.properties overlays # the base settings. See the grouper-loader.base.properties for the possible # settings that can be applied to the grouper.properties

2. Section header starts with a comment with at least 10 hashes, has documentation that starts with two hashes, and ends with a line with at least 10 hashes. Note the first line is the header in the config UI, and the next lines are the description (more info).
   
   

   ######################################## ## Config chaining hierarchy ## configure how configs are read and in what order ########################################

3. Blank line separates items and sections.

4. Config file comment and item has documentation. Comments start with a single hash. Comments can contain json metadata. Metadata can span several comment lines. Item keys and values are separated by an equals and optional whitespace. Metadata must follow comments, not the other way around. After the comment or metadata is the property or whitespace.
   
   

   # seconds between checking to see if the config files are updated # {valueType: "integer", required: true} grouper.config.secondsBetweenUpdateChecks = 60

5. grouper.properties config for DB config (across all configs):
   
   

   # seconds between checking to see if the config files are updated in the database. If anything edited, then refresh all. # Note that the last edited is stored in a config property for deletes. -1 means dont check for incrementals. # Note if *.config.secondsBetweenUpdateChecks is greater than this number # for this config, then it wont update until that amount has passed. # {valueType: "integer", required: true} grouper.config.secondsBetweenUpdateChecksToDb = 60 # seconds between full refreshes of the database config # {valueType: "integer", required: true} grouper.config.secondsBetweenFullRefresh = 3600 # millis since that config inserted, edited or deleted. Grouper will update this config. Do not edit it # Note change this with jdbc and dont audit. # if grouper.config.secondsBetweenUpdateChecks is -1, then dont use this property # {valueType: "integer", required: true} grouper.config.millisSinceLastDbConfigChanged = 0

6. You could comment out one sample value after the metadata which will be used as a sample value. A sample value shows up on the screen but has no value.
   
   

   #auto-create groups (increment the integer index), and auto-populate with users #(comma separated subject ids) to bootstrap the registry on startup #(note: check config needs to be on) # {regex: "configuration.autocreate.group.name.[0-9]+", valueType: "group", required: true} #configuration.autocreate.group.name.0 = $$grouper.rootStemForBuiltinObjects$$:uiUsers

Technical design of retrieving the configuration from the database