SNOW Spoke Server Implementation on SHRINE 1.20.1

1. SNOW Spoke Server Implementation on SHRINE 1.20.1

2. What is the SNOW Network? • SNOW stands for SHRINE Network of Wisconsin • Research network formed by Marshfield Clinic Research Foundation, Medical College of Wisconsin & University of Wisconsin in 2012 • Goal of establishing a shared ontology • Umberto Tachinardi, Tom Mish

3. Goal

4. How to Achieve this Goal • Use the SNOW wiki administered by George Kowalski from MCW • https://wiki.ctri.mcw.edu/pages/viewpage.action?pageId=44991731 • Ask George for credentials to access the wiki • Use the Harvard SHRINE install wiki as a reference: • https://open.med.harvard.edu/wiki/display/SHRINE/Documentation • Follow these instructions • https://wiki.ctri.mcw.edu/display/SNOW/SNOW+Spoke+Implementation+on+CentOS • This will require two shrine.keystore files for each spoke server you build • One for your spoke(s) connecting to the SNOW TEST HUB • One for your site’s spoke(s) connecting to the SNOW PROD HUB • Use tips and tricks in this presentation!

5. SHRINE and i2b2 compatibility

6. System Architecture • Operating System (administrator’s choice) • CentOS 6.6 – tested and approved! • Windows • Database Management System (administrator’s choice) • MySQL, PostgreSQL, Oracle, MSSQL • Linux Services • JBoss, Tomcat, Apache, MySQL, shrine • Software Frameworks in SHRINE application server • Java, J2EE, Scala, Slick, JAX-RS, github.com/typesafehub • Software frameworks for SHRINE web client • PHP, Curl, YUI, FastCGI (on Windows) • Software frameworks in i2b2 • Java, J2EE, Spring Web Framework

7. Client/Server Model (1) • Request: Many based on i2b2 framework • Response: Many based on i2b2 framework • Client: SHRINE web client JavaScript app in browser (spoke) • Authentication: Java Key Store (JKS) SSL certificate • “shrine-client-signed.pem” & PM cell username/password • Server: /opt/shrine/tomcat/webapps/shrine-webclient (spoke) • Topology: Hub and Spoke • Configuration: lstDomains.urlCellPM - /opt/shrine/tomcat/webapps/shrine-webclient/i2b2_config_data.js • Port: 6443 • outbound port 6443 from internal network browser to DMZ firewall • inbound port 6443 from DMZ firewall to internal network browser

8. Client/Server Model (2) • Request: Example: Send marshalled XML from SHRINE web client cohort and send to hub broadcaster • Response: Example: Receive aggregated counts for each downstream node defined on broadcaster • Client: SHRINE adapter forward proxy (spoke) • Authentication: Java Key Store (JKS) SSL certificate • “{site domain}-https.pem” • Server: SHRINE broadcaster reverse proxy (hub) • Topology: Hub and Spoke • Configuration: shrine.queryEntryPoint.broadcasterServiceEndpoint • Port: 6443 • outbound port 6443 on firewall in which spoke resides • inbound port 6443 on firewall in which hub resides

9. Client/Server Models (3) • Request: QEP requests. Example: Send marshalled XML request from initiating spoke adapter off to all spoke server adapters defined • Response: QEP responses. Example: Receive counts for each downstream node • Client: SHRINE broadcaster forward proxy (hub QEPs) • Authentication: Java Key Store (JKS) SSL certificate • - “shrine-hub-https.pem” • Server: SHRINE adapter reverse proxy (spoke) • Topology: Hub and Spoke • Configuration: shrine.hub.downstreamNodes • Port: 6443 • outbound port 6443 on firewall with hub • inbound port 6443 on firewall with spoke

10. Client/Server Model (4) • Request: Example: Send marshalled XML request from downstream spoke server adapter to i2b2 • Response: Example: Receive count from i2b2 based on cohort query • Client: SHRINE data steward • Authentication: i2b2 authorization provider (PM, AD, Shibboleth) • Server: Apache HTTP Server (i2b2 application server) • Topology: Hub and Spoke • Configuration: shrine.steward.pmCellEndpoint (authorization), etc.. • Port: standard HTTP(s) ports • Port 443 if using https protocol in Apache via open_ssl • https://wiki.centos.org/HowTos/Https • Port 80 if using http protocol in Apache

11. Install Non-Requirements • It is NOT required to run SHRINE and i2b2 on the same server • SNOW wiki has instructions for implementation on the same server • It is NOT required to have SHRINE use MySQL and Postgres • SNOW wiki has instructions to configure MySQL and Postgres • It is NOT required to build a test spoke server • SNOW wiki asks you to build a shrine.keystore for the test hub on 1.19.2 and production hub on 1.20.1 for every site spoke server irregardless of whether you build a test spoke server • It is NOT required by Harvard to install SHRINE as root, but you will need to rewrite code if you try • You may run Tomcat as a user other than root

12. Troubleshooting SHRINE Exceptions • SHRINE dashboard • New client application that checks diagnostics of SHRINE configuration • Is this tool helpful? You decide. • Alternate way of troubleshooting SHRINE exceptions? • Check the log files

13. Troubleshooting SHRINE Exceptions Log Files: • /opt/shrine/tomcat/logs/catalina.out • /opt/shrine/tomcat/logs/proxy.log • /opt/shrine/tomcat/logs/shrine.log • /opt/shrine/tomcat/logs/steward.log • /opt/shrine/tomcat/logs/shrine-dashboard.log (wait a minute!) • /opt/jboss-as-7.1.1.Final/standalone/log/server.log You are encouraged to email the University of Wisconsin SNOW hub team with your problems. You cannot test a spoke without a hub.

14. Troubleshooting SHRINE Exceptions • Document exception • Add to SHRINE wiki • Make a copy of the file • Delete log file • Restart service • service mysqld restart (status/start/stop) • service httpd restart (status/start/stop) • service jboss restart (status/start/stop) • /etc/init.d/postgresql-9.1 restart (status/start/stop) • shrine_shutdown / shrine_startup • Ask SNOW hub team for help at UW Health!

15. SHRINE Configuration Files • /opt/shrine/shrine.keystore • /opt/shrine/tomcat/conf/server.xml • /opt/shrine/tomcat/conf/Catalina/localhost/shrine.xml • /opt/shrine/tomcat/conf/Catalina/localhost/steward.xml • /opt/shrine/tomcat/lib/dashboard.conf • /opt/shrine/tomcat/lib/shrine.conf • /opt/shrine/tomcat/lib/steward.conf • /opt/shrine/tomcat/lib/AdapterMappings.xml • /opt/shrine/tomcat/webapps/shrine-webclient/i2b2_config_data.js • /opt/shrine/tomcat/bin/setenv.sh • Ignore line w/ shrine:shrine if Tomcat installed as root • /opt/shrine/tomcat/webapps/shrine-webclient/js-i2b2/cells/SHRINE/cell_config_data.js

16. CentOS Configuration Files • /etc/sysconfig/network • /etc/hosts • /etc/udev/rules.d/70-persistent-net.rules • /etc/sysconfig/network-scripts/ifcfg-eth0 (defined) • /etc/resolve.conf • /etc/nsswitch.conf

17. Nuances on CentOS • JBoss expects localhost.localdomain by default • /etc/sysconfig/network, /etc/hosts or method is defined in /etc/nsswitch.conf • PostgreSQL 9.1 expects localhost as the hostname in its default configuration • /etc/hosts or method is defined in /etc/nsswitch.conf • shrine_shutdown command can cause error “Could not contact localhost” • Be patient after calling shrine_startup before calling shrine_shutdown

18. Hub Connectivity

19. Hub Connectivity

20. SHRINE web client login

21. SHRINE Topics

22. SHRINE Data Steward

23. SHRINE web client cohort

24. SHRINE Topics • Pending - new topics start in the Pending state; researchers must wait for the Steward to approve them • Approved - new topics start in the Approved state; researchers can use them immediately • TopicsIgnoredJustLog - all queries are logged and approved; researchers don't need to create topics

25. Q&A