In most cases, upgrading an existing instance of SHRINE is a relatively quick process. Exceptions to this rule include older versions of SHRINE that contained substantial changes to configuration files and other portions of the file structure. The instructions here specifically describe an upgrade path from SHRINE 1.20 or 1.21 to SHRINE 1.22.8. For instructions on upgrading to SHRINE 1.20, check the child pages underneath the "Archived Upgrade Instructions" section.
- WARNING: Networks will not be able to run a mix of 1.21 and 1.22.8. Nodes running SHRINE 1.22.8 will not trust messages sent by a node running SHRINE 1.21 or earlier, or vice versa. SHRINE 1.22.8 signs and verifies using the Cryptographic Message Syntax (CMS) standard instead of custom code.
This guide makes the following assumptions of a current 1.20 system. Make sure all of these conditions are satisfied before proceeding:
- i2b2 1.7.08b or newer is installed and operational.
- SHRINE 1.20 or 1.21 is installed and operational.
- The SHRINE Data Steward or later has been installed and configured properly.
Before You Start
SHRINE 1.22.8 has new features, some of which require consistent configuration across a network.
Know Your Network-Wide Configurations for New Features
- Which method of re-identification protection does your network use? (required configuration, default provided): In 1.22, we obviate the need for user lockout with new features: greater obfuscation of results, a more interactive Data Steward Application (DSA), and email audit requests from the DSA to the data steward. Lockout remains on by default. (Lockout will be off by default in SHRINE 1.23, and removed in SHRINE 1.24.) Networks should not need both lockout (method employed in 1.21 and prior) and the new re-identification protections introduced in 1.22. We recommend using the new features and turning lockout off if your network governance allows.
- Network contact information (optional configuration): Determine what fields every node should provide via the SHRINE static data service. We created this general-purpose feature to provide contact information for the right person that remote researchers should contact for more information about query results. Networks should agree on key-value pairs to supply for this contact information and any other required information.
- Bot defense values (default values provided, optionally configurable): Determine what values to use for Bot Defense for your network, if other than default.
Know Your Local Configurations for New Features
- Who should get emails generated by SHRINE's Data Steward Application? (optional but highly recommended): Find appropriate email addresses for the system administrators and data stewards.
- How will email from the DSA be sent? (optional but highly recommended): The default configuration assumes localhost is running postfix on port 25 .
- If your network has chosen fields for the SHRINE static data service, what are your local values? (optional, local configuration; see "Network contact information" above)
Shut Down SHRINE
Before starting the upgrade process, make sure SHRINE's Tomcat is not running. Leaving it running during this process can cause problems, especially with unpacking new .war files. Simply run the following command:
Now that SHRINE is stopped, it is a good idea to back up the current versions of the components we will be upgrading. The exact method for making this backups may vary, but these instructions will place the backups in a folder called /opt/shrine/upgrade-backups.
Start by creating a folder to contain these backups:
Make especially sure that the shrine-webclient/ folder is backed up. Later on, we will be restoring important webclient configuration files from this backup. If you choose not to make any backups, make sure to at least keep a copy of i2b2_config_data.js and js-i2b2/cells/SHRINE/cell_config_data.js!
Make especially sure that the shrine.keystore is backed up. If you lose the private side of a cert you may not be able to recover it.
Next, move the current SHRINE webapp folder to the backup location:
Make sure to also back up the other existing SHRINE components (shrine-proxy and steward), just in case:
Next, you want to backup both the shrine.xml and steward.xml file to the backup folder:
Finally remove the old .war files with this command:
Upgrade to JDK 8 and Tomcat 8
SHRINE 1.22.8 was tested only with JDK 8 and Tomcat 8. Future versions of SHRINE will require JDK 8 and Tomcat 8.
Remove the environment variable export from Tomcat
With JDK 8, tomcat no longer needs a MaxPermSize set to run SHRINE. You may remove the part of setenv.sh that set:
or the part of setenv.bat that set:
Deploy New .war Files
Deploy New shrine.war
Next, we will retrieve the new SHRINE webapp from the HMS Sonatype Nexus server at: https://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/shrine-war/1.22.8/. From there, download shrine-war-1.22.8.war to the webapps/ directory on the SHRINE server and rename it to shrine.war.
Deploy New steward.war
Much like shrine.war, the SHRINE Data Steward can be found on the HMS Sonatype Nexus server at https://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/steward/1.22.8/. From there, download steward-1.22.8.war to the webapps/ directory on the SHRINE server and rename it to steward.war.
Deploy New shrine-proxy.war
Like other SHRINE artifacts, the SHRINE proxy can be found on the HMS Sonatype Nexus server at https://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/shrine-proxy/1.22.8/. From there, download shrine-proxy-1.22.8.war to the webapps/ directory on the SHRINE server and rename it to shrine-proxy.war.
Deploy New SHRINE Webclient
The SHRINE webclient can be found on the HMS Sonatype Nexus server at https://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/shrine-webclient/1.22.8/. From there, download shrine-webclient-1.22.8-dist.zip file to the webapps/ directory on the SHRINE server and rename it to shrine-webclient.zip. Then, unzip the shrine-webclient.zip file.
Restore Webclient Backups
After this, restore the previous i2b2_config_data.js and cell_config_data.js files from your backup and place them in the new shrine-webclient folder:
Deploy New SHRINE Dashboard
Like other SHRINE artifacts, the SHRINE Dashboard can be found on the HMS Sonatype Nexus server at https://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/dashboard-war/1.22.8/. From there, download dashboard-war-1.22.8.war to the webapps/ directory on the SHRINE server and rename it to shrine-dashboard.war.
Deploy New SHRINE Node Metadata Service
Like other SHRINE artifacts, the SHRINE Node Metadata Service can be found on the HMS Sonatype Nexus server at https://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/meta-war/1.22.8/. From there, download meta-war-1.22.8.war to the webapps/ directory on the SHRINE server and rename it to shrine-meta.war.
For SHRINE 1.22.8, we strongly recommend that the network configuration is a "Hub-and-spoke". For hub-and-spoke systems, we recommend four certificates in SHRINE's shrine.keystore on nodes:
- The node's signing cert so that its QEP can sign queries.
- The hub's public CA cert so that its adapter can verify other nodes' signatures.
- The hub's public https cert so that the node will trust the hub as a server.
- A cert for this node to use to serve https, referenced in the server.xml file. (Use a cert signed by a public cert authority to avoid a warning in users' browsers.)
See what certs are there and remove any extras. SHRINE will verify that the signing cert is signed by the hub's public cert. Also, check that you are not relying on an expired cert. See Generate a Certificate Signing Request .
Be sure the original keystore is backed up!
You may need to set or update the keyStore keyAlias in server.xml to use your https cert.
These instructions all use mysql syntax. Versions of .ddl files exist for Oracle and MSSQLServer within SHRINE's source code.
SHRINE 1.22.8 adds a table of problems to each SHRINE node, to help diagnose problems observed on that node.
- Add a table named "problems" to the shrine_query_history database
- Expand the limit on the number of characters in a flag message to the database's limit for unbound text in the shrine_query_history database
- Change the PRIVILEGED_USER table's threshold column to accept nulls (and use the default threshold after resetting for lockout) in the shrine_query_history database
- Add a userAudit table to the DSA's database to store when the data steward has been asked to audit a researcher, to stewardDB .
- SHRINE 1.21 added a cache of previous query results to the QEP's qepAuditDB by adding the following tables:
Configure the SHRINE Data Steward
Database - i2b2
The SHRINE Data Steward is typically backed by the i2b2 PM cell used by SHRINE. From the steward application's point of view, all users on the SHRINE project are considered Researchers. However, there is some additional work that has to be done to the i2b2 user list to accommodate the SHRINE Data Steward.
The Steward application requires set of user credentials that it will use to submit queries through to SHRINE. It is recommended that this be a dedicated user separate from any other account. Additionally, it will need to have the parameter "qep" defined (name: qep, value: true, type: text), which can be set in the Manage Users section of the i2b2 Admin Panel.
In shrine.conf, make sure there is a shrineSteward block in the queryEntryPoint section, and that the qepUserName and qepPassword properties match the user with the qep parameter.
In Steward application deployments that require manual topic approval, a trusted user will have to be given permission to review proposed research topics and approve/reject them. To mark a user as such, add the "DataSteward" parameter (name: DataSteward, value: true, type: text) to that user in the Manage Users section of the i2b2 Admin Panel.
Changes to shrine.conf
Consolidation of .conf files
The dashboard.conf, steward.conf, and shrine.conf files have been consolidated into a single shrine.conf file. (The three files had several sections that were duplicated and had to be identical. This should make managing SHRINE's configuration simpler.) All services expect to find all the configuration values they need inside shrine.conf. steward.conf and dashboard.conf will be ignored.
Combine the shrine.conf, steward.conf, and dashboard.conf files into shrine.conf.
See the canonical heavily annotated shrine.conf file in source code control.
Missing Default Properties
Add these section within the shrine block to properly log problems
If you are using hub-and-spoke SHRINE architecture add this setting to shrine.queryEntryPoint
Node Meta Data Service
SHRINE networks now include a JSON api at every node that reports about the contents of the metaData section. What belongs in the metaData section is completely configurable, and we recommend that it be used as a means for serving relevant contact information. Bear in mind that this information is publicly available. For more information on interacting with the Node Data Service, please see the wiki page.
We strongly encourage networks to agree on key-value pairs for contacting remote SHRINE node system admins, data stewards, and data admins. This new service can share that information across the SHRINE network.
Turn Off Adapter Lockout
With more obfuscated results monitored by a data steward, networks can turn off adapter lockout. This feature is on by default in 1.22. In 1.23 adapter lockout will be off by default. In 1.24 the code and database column supporting adapter lockout will be removed.
SHRINE includes a simple mechanism to mitigate the damage that a rogue bot can do if it somehow manages to bypass SHRINE's network security. By default no researcher can run more than 10 queries in one minute, and no more than 200 queries in 10 hours. If you have legitimate bots that operate faster, either turn off this feature or set the counts and time scales to fit those bots' known capability.
We have tested SHRINE's ability to send email via both a local postfix installation and AWS SES. The default configuration should support postfix. You will have to modify the configuration to use AWS SES or other email services. However, SHRINE should be able to use any service that works with a javamail configuration.
Send Email Audit Requests to the Local Data Steward
You must provide email addresses for the "from", "to", and "stewardBaseUrl" fields.
The default values send an audit request to the data steward at 6 AM if any researcher has run more than 30 queries since his last audit, or any researcher has run more than one query in the last 30 days since his last audit. Note that when this system first becomes active the data steward will very likely receive an audit request for queries run in earlier versions of SHRINE.
For Users of Oracle or MS SQL Server
If you experience issues in getting the SHRINE Data Steward (or the new audit logging functionality) working with Oracle or SQL Server, please try the instructions in this article written by a SHRINE developer: Using SHRINE Data Steward with Oracle or SQL Server
This article contains links to alternative database drivers, as well as links to alternative database scripts for creating tables for the SHRINE Data Steward. It also includes information on the necessary changes to make to shrine.xml, steward.xml, and shrine.conf.
shrine.conf includes several instances of slickProfileClassName. By default, these are configured to use MySQL. Users of Oracle or SQL Server for SHRINE must add them. See the below for an example:
Replace "freeslick.driverNameHere$" with the name of the driver you are using ("freeslick.OracleProfile$" for Oracle, and "freeslick.MSSQLServerProfile$" for SQL Server).
To support shrine's improved error message feature, add a context.xml file at /opt/shrine/tomcat/conf/context.xml with contents appropriate for your database:
The only thing left to do at this point is start SHRINE back up. Simply do the following:
Verify SHRINE Upgrade
After starting SHRINE up, verify that the upgrade was properly deployed by checking the SHRINE Dashboard. The exact address you will need to go to depends on your configuration, but the general format looks like the following:
It may take a few seconds for the page to load, but after it does load, log in with your SHRINE credentials (any user will do, regardless of role) and verify that the value for "SHRINE Version" is 1.22.8. If it is still displaying an old version, repeat the instructions in the "Deploy New shrine.war" section, restart SHRINE, and try again.