You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

Upgrading from Grouper v2.1

The following instructions describe how you can upgrade to 2.2 from 2.1.

  1. Items to note in this version of Grouper:
    1. In order to make Grouper more easily deployable across environments, and more easily upgradable, Grouper now has the ability for cascaded config files, and expression language in config file entries.  There can be a default configuration file, and an override file so that only the changes from the default can be tracked in the overlay.  See Grouper configuration overlay.
    2. The legacy style attributes and group types are no longer part of Grouper.  Those legacy APIs still work though; they just use the newer attribute framework.  This upgrade process includes migrating those legacy attributes and group types to the newer attribute framework.
    3. New privileges have been added to determine who has read and update access to attributes based on what the attribute is assigned to.  The new privileges are:  groupAttrRead, groupAttrUpdate, stemAttrRead, stemAttrUpdate, attrDefAttrRead, and attrDefAttrUpdate.  These privileges are not set during the upgrade so if your users need read or update access to attributes and they are not admins of those objects, then the appropriate privilege would need to be assigned.  This applies to attributes originally created using the newer attribute framework as well as attributes using the old attribute framework that would be migrated during this upgrade.
  2. You should get v2.1 versions of the Grouper API, Grouper UI, Grouper WS, Grouper Daemon, etc.  You will need to merge configuration files and JARs.  See the v2.2 change log for more information.  Also keep in mind that some of the configuration files are now handled differently via configuration overlay.  The rest of this document focuses on upgrading the database.
  3. First you may want to analyze your tables to help speed up the upgrade. Analyze your tables.
  4. Stop the Grouper Daemon.  Once you prevent users from making updates to your Grouper instance, run the changeLogTempToChangeLog daemon to clear out the temp changelog using your existing v2.1 API.  Here's an example using GSH. 
    gsh 0% loaderRunOneJob("CHANGE_LOG_changeLogTempToChangeLog")
  5. Before performing any upgrade steps, export your Grouper registry.  Options include performing a database backup (recommended) or using the XML Export utility in Grouper.
  6. Using the 2.2 API, perform a registry check using GSH to create an SQL file that will contain the DDL to update your database. To do this, run: gsh -registry -check     Note you may need to increase memory.  For instance.. 
    $ export MEM_MAX=2000m
$ ./bin/gsh.sh -registry -check
Using GROUPER_HOME: /opt/grouper
Using GROUPER_CONF: /opt/grouper/conf
Using JAVA: java
using MEMORY: 64m-2000m
Grouper starting up: version: 2.2.0, build date: 2014/05/23 13:16:59, env: <no label configured>
grouper.properties read from: /opt/grouper/conf/grouper.properties
Grouper current directory is: /opt/grouper
log4j.properties read from:   /opt/grouper/conf/log4j.properties
Grouper is logging to file:   /opt/grouper/logs/grouper_error.log, at min level WARN for package: edu.internet2.middleware.grouper, based on log4j.properties
grouper.hibernate.properties: /opt/grouper/conf/grouper.hibernate.properties
grouper.hibernate.properties: sa@jdbc:hsqldb:hsql://localhost:9001/grouper
sources.xml read from:        /opt/grouper/conf/sources.xml
sources.xml groupersource id: g:gsa
sources.xml groupersource id: grouperEntities
sources.xml jdbc source id:   jdbc: GrouperJdbcConnectionProvider
This db user 'sa' and url 'jdbc:hsqldb:hsql://localhost:9001/grouper' are allowed to be changed in the grouper.properties
Continuing...
Grouper ddl object type 'Grouper' has dbVersion: 26 and java version: 28
Grouper database schema DDL requires updates
(should run script manually and carefully, in sections, verify data before drop statements, backup/export important data before starting, follow change log on confluence, dont run exact same script in multiple envs - generate a new one for each env),
script file is:
/opt/grouper/ddlScripts/grouperDdl_20140523_13_19_30_162.sql
Note: this script was not executed due to option passed in
To run script via gsh, carefully review it, then run this:
gsh -registry -runsqlfile /opt/grouper/ddlScripts/grouperDdl_20140523_13_19_30_162.sql
    1. In this example above, an SQL script called /opt/grouper/ddlScripts/grouperDdl_20140523_13_19_30_162.sql was created.
    2. Postgres only - If using postgres, you should see foreign keys being dropped at the top of the script. If not, try setting the ddlutils.schema grouper.properties setting and run again. If you still don't see foreign keys being dropped at the top of the script, manually drop all foreign keys before running the script.
    3. Postgres and hsql only - You should backup any non grouper views that depend on Grouper views, run the grouper script (which deletes those views due to drop view cascade), and then you should recreate those non grouper views.
  7. Run the SQL script.  To do this, run:  gsh -registry -runsqlfile /path/to/sql/file.sql  For instance.. 
    $ ./bin/gsh.sh -registry -runsqlfile /opt/grouper/ddlScripts/grouperDdl_20140523_13_19_30_162.sql
Using GROUPER_HOME: /opt/grouper
Using GROUPER_CONF: /opt/grouper/conf
Using JAVA: java
using MEMORY: 64m-2000m
This db user 'sa' and url 'jdbc:hsqldb:hsql://localhost:9001/grouper' are allowed to be changed in the grouper.properties
Continuing...
Script was executed successfully

Grouper starting up: version: 2.2.0, build date: 2014/05/23 13:16:59, env: <no label configured>
grouper.properties read from: /opt/grouper/conf/grouper.properties
Grouper current directory is: /opt/grouper
log4j.properties read from:   /opt/grouper/conf/log4j.properties
Grouper is logging to file:   /opt/grouper/logs/grouper_error.log, at min level WARN for package: edu.internet2.middleware.grouper, based on log4j.properties
grouper.hibernate.properties: /opt/grouper/conf/grouper.hibernate.properties
grouper.hibernate.properties: sa@jdbc:hsqldb:hsql://localhost:9001/grouper
sources.xml read from:        /opt/grouper/conf/sources.xml
sources.xml groupersource id: g:gsa
sources.xml groupersource id: grouperEntities
sources.xml jdbc source id:   jdbc: GrouperJdbcConnectionProvider
  8. Now that the DDL updates have been made, there are a few additional GSH scripts that need to be run.
    1. Clear the temp change log before we start. 
      gsh 0% loaderRunOneJob("CHANGE_LOG_changeLogTempToChangeLog")
    2. Add group sets for new privileges (groupAttrRead, groupAttrUpdate, stemAttrRead, etc) 
      gsh 1% new AddMissingGroupSets().addMissingSelfGroupSetsForGroups()
gsh 2% new AddMissingGroupSets().addMissingSelfGroupSetsForStems()
gsh 3% new AddMissingGroupSets().addMissingSelfGroupSetsForAttrDefs()
    3. Add new privileges to point in time (groupAttrRead, groupAttrUpdate, stemAttrRead, etc) 
      gsh 4% new SyncPITTables().processMissingActivePITFields()
    4. Remove old fields (legacy attributes) from point in time. 
      gsh 5% new SyncPITTables().processMissingInactivePITFields()
    5. Migrate legacy attributes 
      gsh 6% new MigrateLegacyAttributes().saveUpdates(true).fullMigration()
    6. Add stem sets 
      gsh 7% new SyncStemSets().fullSync()
    7. Add group sets for new privileges to point in time (groupAttrRead, groupAttrUpdate, stemAttrRead, etc) 
      gsh 8% new SyncPITTables().sendFlattenedNotifications(false).processMissingActivePITGroupSets()
  9. Analyze your tables. (Again to avoid any performance issues.)
  10. Start the Grouper Daemon and all other Grouper components (UI/WS).
  11. The legacy attributes were backed up in separate tables.  After verifying that everything is okay, you can drop those backed up tables by setting ddlutils.dropLegacyAttributes = true in grouper.properties, running gsh -registry -deep and then executing the SQL file.
  • No labels