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/011/4ALLALL4.16.0Medium important

GRP-5794

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/09/11ALLALL4.15.3Not important

GRP-5665

You want to use Playwright browser automation for UI sanity testing

Set this variable if you want the playwright jar in the lib dir:


GROUPER_PLAYWRIGHT_MOVE_JARS=true 


Install playwright libs in derived image (recommended)


RUN . /usr/local/bin/librarySetupFilesForComponent.sh && setupFilesForComponent_playwrightInstallOsLibsHelper && setupFilesForComponent_unsetAll


Set this variable to install OS libs on startup (must be root, recommend to do derived image instead, takes extra time on startup to install)


GROUPER_PLAYWRIGHT_INSTALL_OS_LIBS=true 
2024/09/11ALLALL4.15.3Important

GRP-5588

You use Grouper WS

Set this variable in the WS container:

GROUPERWS_URL_WITH_CONTEXT_NOSLASH=https://myws.inst.edu/grouper-ws

Test swagger after build: https://myws.inst.edu/grouper-ws/docs
See Jira or Container docs for details

2024/08/26ALLALL4.15.0Medium important

GRP-5625

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/08/26ALLALL4.15.0Important

GRP-5653

You run commands in the OS during container build or run

The OS was upgraded from Rocky 8 (which is not unsupported) and Rocky 9.  See the Jira for notes but some things are a little different
like "yum" is not there anymore.  Check the output of building and running Grouper to see if there are any errors.

2024/08/244.10.34.11.0-4.14.34.11.0Important

GRP-5635

You have one or more Recent memberships loader groups, and the CHANGE_LOG_consumer_recentMemberships job is failing

Run this gsh script to fix

import edu.internet2.middleware.grouper.app.serviceLifecycle.GrouperRecentMemberships

def group = GroupFinder.findByName("etc:attribute:recentMemberships:grouperRecentMembershipsLoader", true)

GrouperRecentMemberships.setupRecentMembershipsLoaderJob(group)
2024/07/30ALLALL4.12.1Important

GRP-5408

You have an AWS provisioner

The AWS target throws a 400 if there is an active flag on SCIM group create.  In the Group section of the config, you must set "include active on group create" to false

2024/07/16ALLALL4.14.1Medium important

GRP-5548

If you have SCIM provisioners

The provisioner will now select memberships from the target of SCIM provisioners.  To keep the old behavior, change the membership CRUD configuration to not select memberships.  Run the full in readonly mode and check what will be changed in the debug object logs.

2024/06/27ALLALL4.14.0Medium important

GRP-5514

If you run Grouper

If your DB credential cannot do DDL then add tables 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.

2024/06/27ALLALL4.14.0Medium important

GRP-3981

If you have an SQS external system

Enter in the secret key for sqs in your external system and save, if you
look for the external system config id in grouper.client.properties, there
a typo you can remove:


grouper.messaging.system.myAwsMessagingSystem.secretyKey

You need to add the region to the external system

2024/06/174.9.3+ALL4.14.0Medium importantGRP-5450

If you have httpClientReuse=true in grouper.properties

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

2024/06/25ALLALL4.13.1Medium important

GRP-5515

If you allow colons in passwords through basic auth

Read the documentation and set an environment variable to allow passwords to end in colons

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

GRP-5379

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

GRP-5312

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

GRP-5268

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

GRP-5340

You run Grouper and have any rules

2024/02/274.10.3ALL4.11.0Medium important

GRP-5310

You use self signed certs for tomcat

See Jira and adjust env vars

2024/02/27ALLALL4.11.0Medium important

GRP-5302

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

GRP-5228

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

Set this variable:  GROUPER_TOMCAT_LOG_ACCESS_DIRECTORY=/tmp

2023/12/27ALLALL4.10.0Medium important

GRP-5218

If you set this in grouper.properties

grouper.json.serialize.deserialize.useLegacy = true

Remove it

2023/12/27ALLALL4.9.3Medium important

GRP-5170

If you patched GSH templates in 4.9.0 or 4.9.1

Remove the patch

2023/12/27ALLALL4.10.0Medium important

GRP-5195

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

GRP-5130

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)
zoom.myConfigId.licenseReactivatedUsers
2023/11/20ALLALL4.9.0Medium important

GRP-5139

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

GRP-5140

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

GRP-5141

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

GRP-5142

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

GRP-5082

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

GRP-5107

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

2023/10/04ALLALL4.7.0ImportantGRP-4946

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)

2023/10/04ALLALL4.7.0ImportantGRP-5005

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.

2023/09/08ALLALL4.6.0ImportantGRP-4932

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

GRP-4694


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

GRP-4610

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

GRP-4679

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

GRP-4625

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

GRP-4633

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
2023/03/13ALLALL4.0.3Important
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

xxx/jre/lib/security/xxx

Change it to

xxx/lib/security/xxx
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+)
or
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
2023/03/01ALLALL4.0.1Important

Check your derived image build and make sure it works with Rocky linux.  It is intended to be a drop in replacement
2023/03/01ALLALL4.0.1Important


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

2023/03/01ALLALL4.0.1Important
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
2023/04/28ALLALL4.0.1Important
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
2024/01/19ALLALL4.0.1Important
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