When upgrading from Grouper v4 to another v4 container, this wiki will consolidate all the steps needed to perform that upgrade.

See information on Grouper Versioning here

Note, these are in reverse order, so go from bottom to top

DateUpgrading from versionUpgrading to VersionNote for versionImportanceJiraStep needed if...Description
2024/06/174.9.3+ALL4.13.1Medium importantGRP-5450

If you have httpClientReuse=true in grouper.properties

You can remove that setting as the bug there was fixed.

2024/05/26ALLALL4.13.0Not importantGRP-5395

You run Grouper

Tomcat was upgraded to v9, make sure any tomcat things work in UI/WS, including logs, SSL, authentication, etc

2024/03/19ALLALL4.12.0Not important


You run Grouper

Tomcat was upgraded, make sure any tomcat things work in UI/WS, including logs, SSL, authentication, etc

2024/03/10ALLALL4.11.0Medium important


If you use the provisioning framework and have too much memory allocated to your daemon

Try bumping down your daemon memory to 16g (16g in container and 13g heap) and see if you still have memory problems. 
Or if you had more than 32g, try 32g container and 28g heap.

2024/03/03ALLALL4.11.1Not important


You run Grouper and use the daemon screen

Note that the change log temp daemon and composite change log consumer run continuously. 
If you want to see progress show subjobs (checkbox is default checked in v5)

2024/03/03ALLALL4.11.1Not important


You run Grouper and have any rules

2024/02/274.10.3ALL4.11.0Medium important


You use self signed certs for tomcat

See Jira and adjust env vars

2024/02/27ALLALL4.11.0Medium important


If you use Grouper

If your grouper credential cannot do DDL, see the Jira and run the DDL manually.

Otherwise, after the OTHER_JOB_upgradeTasks job runs, the DDL will be added.  Look at the job message to confirm that there were no issues adding the DDL.

2024/01/01ALLALL4.10.2Medium important


If you expect tomcat access logs to be in /tmp (previous default), they are not in /opt/grouper/logs


2023/12/27ALLALL4.10.0Medium important


If you set this in grouper.properties

grouper.json.serialize.deserialize.useLegacy = true

Remove it

2023/12/27ALLALL4.9.3Medium important


If you patched GSH templates in 4.9.0 or 4.9.1

Remove the patch

2023/12/27ALLALL4.10.0Medium important


If you use Grouper

If you have extra indexes on grouper_loader_log, you can remove them. 

If your DB credential cannot do DDL then add indexes manually from Jira

Otherwise, after the OTHER_JOB_upgradeTasks job runs, the DDL will be added.  Look at the job message to confirm that there were no issues adding the DDL.

2023/11/26ALLALL4.7.0Medium important

If you have a MidPoint provisioner and do not have foreign keys with cascade delete

Either drop the MidPoint tables and use the new DDL, or add cascade delete to the foreign keys on the attribute and membership tables

2023/11/20ALLALL4.9.0Medium important


If you use the zoom provisioner / loader

A 3rd party library was updated for security, test your integration.  Note set this
explicitly in grouper-loader.properties, the default will change from true to false.

# if reactivating users, this will assign a license (user type 2)
2023/11/20ALLALL4.9.0Medium important


If you use the OIDC for UI/WS authentication

A 3rd party library was updated for security, test your authentication

2023/11/20ALLALL4.9.0Medium important


If you use the legacy (non provisioning framework) box provisioner

A 3rd party library was updated for security, test your provisioner or upgrade to the
provisioning framework

2023/11/20ALLALL4.9.0Medium important


If you use the legacy (non provisioning framework) google apps provisioner

A 3rd party library was updated for security, test your provisioner or upgrade to the
provisioning framework

2023/11/20ALLALL4.9.0Medium important


If you use Grouper

JSON marshalling changed to be higher performance and less likely to 
leak memory.  You can use this in grouper.properties to revert to old if you have an issue:

grouper.json.serialize.deserialize.useLegacy = true

Report any issues you have if you have to revert

2023/11/20ALLALL4.9.0Medium important


If you LDAP loaders of type: list of groups or groups from attributes, and grouper-loader.properties:

loader.ldap.requireTopStemAsStemFromConfigGroup = true or default

You can now specify any stems to be the top stem, or you can
use a stem near the loader configured group.  After upgrading, run the diagnostics
or full sync on your loader and make sure the destination stays the same and 
does not change.  Might want to temporarily remove the SQL like string
if applicable so the existing groups do not get deleted.

2023/11/04v2.5.0-v2.5.68, v4.0.0-v4.7.2ALL4.8.0Not important


If you were affected by the authentication bypass vulnerability and installed the remediation


If you use provisioning

If you provision based on attribute (e.g. netId or eppn), and the provisioner cannot work if the value is
null, and some subjects dont have that attribute, and you dont want it to raise an error (even if error
is ignored), then configure the provisioner attribute to not provision the object if the attribute is null.
(under validation settings... see the jira)


If you want database connection pool size to differ based on UI/WS/daemon
(e.g. if you have problems with daemon performance or reliability)

You can set the env var in container for DB pool size: GROUPER_DATABASE_CONNECTION_POOL_SIZE

You can allow the daemon to use more connections than UI/WS.  For instance, the daemon should probably have
twice the pool size as a UI/WS.  Do some math based on how maybe connections your DB supports, and how
many nodes of each type you have.

For instance, if you have 500 connections max at DB, and 2 daemon, 2 ui, and 2 ws, might want to set var for
daemon to be 110, and ui/ws to be 55.


If you have SSL certs in /etc/pki/java/cacerts

(if your SSL if not in trusted roots)

You can be doing one of three things with SSL certs:

  1. Putting them in the container in /etc/pki/java/cacerts
    1. You need to switch to method #2 or #3 (either #2 or #3 is preferred, #2 is best) or add /etc/pki/java/cacerts as java trust store (not preferred)
  2. Putting them in /opt/grouper/certs/client
    1. This requires no change
  3. Putting them in $JAVA_HOME/lib/security/cacerts
    1. This is not common, but requires no change

Test anything that uses certs added to Java after upgrade (e.g. connections to SQL, LDAP, WS, etc outbound from Grouper)

2023/07/25ALLALL4.5.0Not importantGRP-4843You use GSH templates

If you want a run button from the misc → GSH template screen, edit the template and pick the group or folder it should run from default

2023/07/04ALLALL4.4.0Not importantGRP-4816You use SQL sync

Multiple source records with same key in SQL sync will cause daemon error (you can configure to ignore this if expected)

2023/06/27ALLALL4.4.0, 4.3.0ImportantGRP-4803You customize any tomcat config files

The tomcat version changed so make sure any patches or edits or overrides to the tomcat server.xml config files are correct

2023/06/27ALLALL4.3.0ImportantGRP-4805You use a box external system with a proxy and not default port

Set the proxy URL in the external system instead of the host and port

2023/06/06ALLALL4.2.0ImportantGRP-4768You use Grouper

If your database can support 500 connections for each node in your env, then you do not need to do anything.
Otherwise, increase the number of connections your database can support, or change the pool size in grouper.hibernate.properties
(used to be 100).  Note that file is in the container and cannot be changed dynamically

hibernate.c3p0.max_size = 500
2023/05/05ALLALL4.1.6Medium important


You use GrouperUpgrade the grouper_memberships_lw_v (manually).  Note this is for performance, so this is optional
2023/04/26ALLALL4.1.4Not important


If you do not want diagnostics to fail for a dayRun the daemons: syncAllPitTables, syncAllSetTables
2023/03/26ALL4.1.1 or older4.1.2Important


If you lock down UI configuration to ipv6 without a mask, or multiple ipv6 comma separatedWill work in 4.1.2+.  Before this version, use one network and use a net mask.  Or use ipv4.
2023/03/26ALLALL4.1.1ImportantGRP-4657If you have provisioners

In order to help with renames, and delete/create same provisionable grouper object:

For entities and groups, you should probably cache your search/match attribute in addition to the "link" cache (e.g. ldap_dn for ldap or id for web service)

For entities and groups, you should add a second search/match attribute for the "link" attribute 

2023/03/26ALLALL4.1.1Not important


If you want auto-ddl configured correctlyThis is not necessary, but if you set auto-ddl in grouper.hibernate.properties to 4.999.999 per previous instruction, you can now set to 4.*.*
2023/03/26ALLALL4.1.1Not important


If you want the previous default behavior where all users will see some attributes in etc folderReconfigure if you want the previous behavior.  Recommended not to do this.  You should probably assign READ/UPDATE privs on those attributes for power users only
If you reference cacerts or other trust store files or folders in your Dockerfile or configuration (e.g. rabbitmq external system)

If you reference cacerts or other trust store files or folders, the path changed in java17, if you have something like


Change it to

2023/03/13ALL4.0.3- only4.0.1Important
If you have auto ddl configured in grouper.hibernate.properties

Note, do not change this if upgrading to 4.1.0+

Change auto DDL to

4.*.*    (4.0.4+)
4.9999.9999 (4.0.1)
2023/03/10ALLALL4.0.1Not importantGRP-4619

If you have a provisioner translation that checks for nulls in a terniary operator, e.g.

${grouperProvisioningGroup ? x :y}
Reconfigure to check for nulls per jira

Check your derived image build and make sure it works with Rocky linux.  It is intended to be a drop in replacement

You have a subimage or scripts that use the tomee directory

GRP-4567: either make a symlink from /opt/tomcat to /opt/tomee, or change your scripts to point to /opt/grouper/tomcat

Change ENV container vars from TOMEE to TOMCAT

You have a custom provisionerThe API and capabilities changed slightly, please discuss with Chris on slack
2023/03/01ALLALL4.0.1Not important
You use the legacy SCIM WS (not provisioning!)This has been rewritten and needs to be adjusted from clients.  We are not aware of anyone using this
You mount the log directory to the container or use uids and gids somewhere from the containerThe tomcat user uid in the container is 996 (was 998), and the group is now 994 (was 997).  You might need to adjust the uids/gids or adjust permissions
You use kerberos for WS authn

Java 17 has stricter encryption types.  If authentication is having issues you might either need to change the passwords of old credentials to a newer encryption type, or allow old encryption types in the /etc/krb5.conf.  Add something like this:

allow_weak_crypto = true
permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1
default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1
default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1

  • No labels