API Building & Configuration

Building the Grouper API

The Grouper API is provided both as a binary and source distribution. Note the Grouper Installer will install the binary grouper API.

To build the source distribution :

cd grouper-api-1.5.0
ant dist

Testing the API is performed using GrouperShell :

Testing will destroy any pre-existing data in the Groups Registry database

bin/gsh.sh -test -all

Configuring the Grouper API

This section describes all of the Grouper API configuration files and important settings.

Starting with Grouper 2.2 it is highly recommended that you restructure your configuration files to use Configuration Overlays.

The Grouper API is distributed with example configuration files with ".example" inserted in the middle of their names. These should be renamed or copied to remove the ".example" substring, or doing a build with ant will do this, or it is already copied in the binary distribution. e.g. for grouper.properties, the example file is grouper.example.properties.

Section	Configuration File	Purpose
Database-Related Settings and Procedures	grouper.hibernate.properties	integrating the Grouper API with the database that will house your Groups Registry
Configuration of Source Adapters	sources.xml	integrating the Grouper API with chosen identity sources
Grouper properties	grouper.properties	defaults for Grouper privileges, enabling identified external users to act with elevated root-like privilege, changing the display name for internal subjects
Logging	log4j2.properties	logging
Daemon	grouper-loader.properties	auto-load memberships from external sql sources, register notification consumers, validate Grouper Rules, update enabled/disabled flags, etc

Database-Related Settings and Procedures

Database Driver Location

Place the jar file containing the JDBC driver for your database in the lib/custom/ directory. The Grouper v1.5.0 package includes the JDBC driver for HSQLDB v1.8.0.10. Sample JDBC drivers are located in lib/jdbcSample (e.g. for Oracle, MySQL, and PostgreSQL).

General Property Settings

Grouper uses Hibernate to persist objects in the Groups Registry. Database-specific settings are configured in conf/grouper.hibernate.properties, which has pre-populated examples for HSQLDB, MySQL, Oracle, and Postgresql.

Required properties are:

Property Name	Purpose
hibernate.connection.driver_class	JDBC driver classname
hibernate.connection.url	JDBC URL for the database
hibernate.connection.username	database user
hibernate.connection.password	database user's password Note, you can also put a filename of the encrypted password
hibernate.dialect	classname of a Hibernate dialect, for setting platform specific features. Choices are listed (Hibernate Reference Documentation - Chapter 3. Configuration - 3.3. JDBC connections - 3.4.1. SQL Dialects) here

You may need to refer to your database support person to determine these required properties.

Detailed Hibernate configuration documentation is available (Hibernate Reference Documentation - Chapter 3. Configuration - 3.3. JDBC connections) here.

MySQL Transaction Support

If you want transactions to work (i.e. when doing a unit of work in grouper, it either all completes or none), which is definitely recommended, though not required, your mysql table format needs to be transactional, e.g. innodb, which is not the default (myisam is the default). One way to enable innodb in mysql is with this line in the my.cnf: default-storage-engine=innodb

MySQL/MariaDB Character Set and Performance Settings

For MySQL and MariaDB, the following settings are recommended.

character-set-server = utf8
collation-server = utf8_bin
innodb_buffer_pool_size = 4G

utf8mb4 is not recommended because the database engines in MySQL/MariaDB that support transactions have limitations on the length of prefixes for indices. For InnoDB and XtraDB, the prefix is limited to 767 bytes. When using utf8mb4, where 4 bytes are used instead of 2, the prefixes used for some Grouper tables are too long.

You can also consider setting innodb_flush_log_at_trx_commit = 2. The default setting of 1 is required for full ACID compliance and logs are written and flushed to disk at each transaction commit. However, this can be expensive in terms of disk I/O. With a setting of 2, logs are written after each transaction commit and flushed to disk once per second. Transactions for which logs have not been flushed can be lost in a crash. The tradeoff here may be acceptable in your environment.

For those running MariaDB you should read this knowledge base article about OPTIMIZE and defragmenting. Some have found MariaDB 10.3+ to be a good, fast variant of MySQL for use by Grouper.

Database Allow changes and Deny

Some database operations (such as dropping tables or recreating data during tests) require confirmation of a prompt asking whether or not to continue. It is possible to automatically allow or deny these database operations in conf/grouper.properties :

# allow and deny for db data or object deletes.
# if a listing is in the allow, it will be allowed to delete db
# if a listing is in the deny, it will be denied from deleting db
# multiple inputs can be entered with .0, .1, .2, etc. These numbers must be sequential, starting with 0
db.change.allow.user.0=grouper3
db.change.allow.url.0=jdbc:mysql://localhost:3306/grouper3?useSSL=false
db.change.allow.user.1=grouper1
db.change.allow.url.1=jdbc:mysql://localhost:3306/grouper1?useSSL=false

db.change.deny.user.0=grouper2
db.change.deny.url.0=jdbc:mysql://localhost:3306/grouper2?useSSL=false

Database Initialization Procedure

Database initialization is performed using the GrouperShell.

Initializing the database will destory any pre-existing data

To initialize the Groups Registry and install tables, populate default group types and fields, and create the root naming stem :

bin/gsh.sh -registry -check -runscript

To re-initialize the Groups Registry (e.g. after running junit tests) :

bin/gsh.sh -registry -reset