CONNECT Solaris Full Binary System Installation and Configuration Manual

Transcription

1 CONNECT Solaris Full Binary System Installation and Configuration Manual Version 1.0 CONNECT Release July 2009

2 REVISION HISTORY REVISION DATE DESCRIPTION - 13 May 2009 Initial Release - 15 May 2009 Update to include instructions to enable additional logging. Also added comment for know WARNING for Name Value Pairs messages July 2009 Updated to reflect Release 2.1 CONNECT_Solaris_Full_Binary_Manual i Release 2.1

3 TABLE OF CONTENTS 1.0 INTRODUCTION PURPOSE SCOPE DOCUMENT DESCRIPTION REFERENCED DOCUMENTS CONNECT INSTALLATION CHECKLIST INSTALLATION AND CONFIGURATION CHECKLIST OID REQUEST SUBMITTAL PROCESS TEST DEPLOYMENT FOOTPRINT HARDWARE REQUIREMENTS SOFTWARE REQUIREMENTS FEDERAL GATEWAY INTERFACE (WSDL) PORTS SOLARIS INSTALL AND CONFIGURATION INSTRUCTIONS INSTALL PREREQUISITE SOFTWARE ON SOLARIS JDK INSTALLATION GLASSFISHESB INSTALLATION CONFIGURATION UPDATE PROPERTY/CONFIGURATION FILE SETTINGS GATEWAY.PROPERTIES THIRD PARTY COMPONENTS COMPONENT CATALOG INSTALLATION OF THIRD PARTY COMPONENTS INSTALLATION OF GNU TAR INSTALLATION OF LIBICONV LIBRARIES INSTALLATION OF LIBINT LIBRARIES INSTALLATION OF GCC LIBRARIES INSTALLATION OF LOG4J INSTALLATION OF COMMONS LOGGING INSTALLATION OF C3P INSTALLATION OF HIBERNATE INSTALLATION OF COPYV INSTALLATION OF METRO INSTALLATION OF CONNECTOR/J FOR MYSQL INSTALLATION OF XSTREAM INSTALLATION OF SPRING FRAMEWORK INSTALLATION OF SOAPUI CONFIGURE THIRD PARTY COMPONENTS IN GLASSFISH INSTALL AND CONFIGURE MYSQL INSTALLATION STARTING AND STOPPING MYSQL CONFIGURING MYSQL...28 CONNECT_Solaris_Full_Binary_Manual ii Release 2.1

4 7.0 SSL CERTIFICATE REQUEST AND INSTALLATION PROCESS SETUP GENERATE CERTIFICATE REQUEST DOWNLOAD ROOT CERTIFICATE SEND CERTIFICATE REQUEST INSTALL THE CERTIFICATE NHIN-CONNECT SERVER CONFIGURATION CONFIGURATION SETTINGS METRO 1.4 INSTALLATION SETTINGS GLASSFISH APPLICATION VARIABLES CONNECTION MANAGEMENT INTERNALCONNECTIONINFO.XML FILE REIDENTIFICATION.XML GATEWAY PROPERTIES ADAPTER PROPERTIES CONNECTION EPR PROPERTIES COMPONENT PROXY SPRING CONFIGURATION PROPERTIES HIEM TOPIC CONFIGURATION PROPERTIES DEPLOYMENT DEPLOYING APPLICATIONS TO GLASSFISH ADAPTER COMPONENTS GATEWAY COMPONENTS UPDATE GLASSFISH LIB DEPLOYMENT OF CONNECT DEPLOYMENT OF THE ADAPTER AND GATEWAY TO SINGLE MACHINE CONFIGURATION FILES ACRONYMS...48 A. OID REQUEST SUBMITTAL PROCESS... A-2 A.1 GETTING STARTED... A-2 A.2 SUBMITTING THE REQUEST... A-2 A.3 SEARCHING FOR AN OID ON THE SITE... A-8 CONNECT_Solaris_Full_Binary_Manual iii Release 2.1

5 LIST OF FIGURES Figure 6.1-1: Glassfish Welcome Screen...9 Figure 6.1-2: Glassfish License Agreement...10 Figure 6.1-3: NetBeans Screen...11 Figure 6.1-4: Glassfish Screen...12 Figure 8.1-1: Manage Application Variables...35 Figure A.2-1: HL7-OID Registration Home Page... A-2 Figure A.2-2: Complete Contact Information... A-3 Figure A.2-3: Select type of OID... A-4 Figure A.2-4: New or Existing OID Designation... A-5 Figure A.2-5: HL7 OID Description... A-5 Figure A.2-6: OID Registration Confirmation... A-6 Figure A.2-7: OID Confirmation... A-6 Figure A.3-1: Searching by OID number... A-8 Figure A.3-2: Search by OID Description... A-9 CONNECT_Solaris_Full_Binary_Manual iv Release 2.1

6 1.0 INTRODUCTION 1.1 Purpose This document is the installation and configuration manual for installing the Full Binary installation of the CONNECT software on the Solaris Operating Systems. This document targets the installation and configuration of the Core Gateway components. A follow-up release of this document will target the Enterprise Level Components of the CONNECT software (OpenSSO, Jericho, NIST Repository and Mural). Some components required during the installation and configuration of the CONNECT software require privileged access to the target machine. The recommended configuration for Solaris is to create a separate partition for the installation and configuration of the third-party products used by the CONNECT gateway. For the purposes of this installation manual, that partition is named /nhin. The privileged account can be the root or another account that has the required privilege for the successful execution of the pkgadd command. If the target machine already has GNU tar installed, no privileged access is required. 1.2 Scope The procedures in this document are applicable to all CONNECT users running the Solaris Operating System. 1.3 Document Description This document includes the following sections: Section 1.0 Introduction Section 2.0 Referenced Documents Section 3.0 CONNECT Installation Checklist Section 4.0 OID Request Submittal Process Section 5.0 Test Deployment Footprint Section 6.0 Solaris Install and Configuration Instructions Section 7.0 SSL Certificate Request and Installation Process Section 8.0 NHIN-CONNECT Server Configuration Section 9.0 Deployment Section 10.0 Acronyms 2.0 REFERENCED DOCUMENTS N/A 3.0 CONNECT INSTALLATION CHECKLIST The following is a workflow/checklist that guides the reader through the steps required to join the Nationwide Health Information Network (NHIN) using the CONNECT Gateway. This document is organized to follow the flow of the workflow/checklist below. CONNECT_Solaris_Full_Binary_Manual 1 Release 2.1

7 OID Request Process Submit a request for an OID for each gateway being configured. Assess Hardware Requirements Ensure to secure hardware that meets the hardware and software requirements provided for the appropriate platform. Determine Installation Method Obtain Media/ Software Perform Installation Request and Install SSL Select an installation method: Manual, install from a zip or install a VM Gateway image. As applicable, download the Gateway VM software, Gateway Software zip or tar file Follow the installation instructions for zip or tar as appropriate. Instructions on how to request and install the SSL the CONNECT gateway. Step to be executed by Agency Step executed by Agency & CONNECT Team Step executed by Agency & CSC Configure the Gateway Configure the specific gateway properties depending the Agency s needs and platform selected CONNECT_Solaris_Full_Binary_Manual 2 Release 2.1

8 3.1 Installation and Configuration Checklist Item Procedural Step Download and install JDK 1.6.0_13. This is the version that the current NHIN CONNECT Gateway was developed against and the recommended version. See section Download and install GlassFishESB, v2.1. This is available from the CONNECT Portal. See section Download, install and configuration of MySQL database. This is available from the CONNECT Portal. See section 6.4. Download and install log4j logging components. The NHIN CONNECT Gateway used log4j for logging and debugging purposed. If issues should occur on a deployed Gateway, these log files are critical in determining the issue and seeking resolution. This is available from the CONNECT Portal. See section Download and install soapui test suite. The NHIN CONNECT Gateway is deployed with a test suite to verify the installation. These tests were generated using soapui. This is available from the CONNECT Portal. See section Install Third-party component libraries and jars into $AS_HOME/lib. See section Install and configure Metro 1.4 This is available from the CONNECT Portal. See section Obtain certificates from the Certificate Authority. Configure 2-way SSL using the production certificates received. See section 7.0. Define environment variables used during deployment. See section 8.0. Deploy NHIN CONNECT Gateway using the Glassfish Admin Console, deploy each of the Composite Applications within Glassfish. See section 9.1. Configure the NHIN CONNECT Environment including updates to properties files. The properties files are used to customize installation for each specific install. See section 8.0. Verify Application Server and Deployment via execution of soapui tests. See section OID REQUEST SUBMITTAL PROCESS Each gateway has a unique identifier known as the OID (Object Identifier) or Home Community ID. The instructions in Appendix A can be used to request an OID. However, the instructions needed to obtain an OID may be slightly different due to ongoing updates to the site. CONNECT_Solaris_Full_Binary_Manual 3 Release 2.1

9 5.0 TEST DEPLOYMENT FOOTPRINT 5.1 Hardware Requirements This section describes the recommended minimum hardware component infrastructure including processor performance, disk space, and RAM for the application server platform. This is provisional information subject to change based on continued development. The Connect software requires two machines, each with the following minimum specifications : Item Version 2.0 Processor Minimum dual 2GHz UltraSPARC RAM Minimum of 4 GB Hard Disk Size Application Dependent on the deployment configuration. For sizing purposes, assume 100K per CCD record, 1K per audit log record. Hard Disk Speed Minimum of 7200 RPM and RPM preferred. Network Interface 100MB Ethernet acceptable; 1GB Ethernet desirable 5.2 Software Requirements This section describes any dependent software products. Item Description Applies to Gateway Version Platform Operating System Operating system supported by Glassfish v2 and GlassFishESB v2.1. For additional information, refer to the specific installation instructions for Solaris. All Server CONNECT_Solaris_Full_Binary_Manual 4 Release 2.1

10 Item Description Applies to Gateway Version Platform Java-JRE/JDK Java SDK 1.6 Update 13 All Server Application Server Glassfish v2.1 (9.1.1) build b60e-fcs [This is bundled with the GlassFishESB] All Server Enterprise Service Bus (ESB) GlassFishESB v2.1 build All Server Communicatio n Stack Metro v1.4 All Server Network Protocol TCP/IP All Server/Client Relational Database Any ANSI SQL92 compliant relational database. For example, MySQL 5.0, Oracle, and DB2 1.0 Server Recommende d Dev Environment (Optional) Netbeans build All Server/Client Recommende d Test Tools (Optional) soapui v2.5.1, JUnit All Client 5.3 Federal Gateway Interface (WSDL) Ports The table below identifies all of the currently public WSDL Interfaces supported by the Federal Gateway. This table includes the name of the WSDL, the services it handles, the port number, whether or not it is configurable, and whether or not it is SSL. All ports in the NHIN-CONNECT Gateway are configurable via either the Glassfish or Http Binding Component port settings. CONNECT_Solaris_Full_Binary_Manual 5 Release 2.1

11 WSDL Services Port SSL AdapterAuditLogQuery Audit Log Query HttpDefaultPort No AdapterDocQuery Document Query HttpDefaultPort No AdapterDocRetrieve Document Retrieve HttpDefaultPort No AdapterReidentification Subject Discovery - Reidentification HttpDefaultPort No AdapterSubjectDiscovery Subject Discovery - Announce and Revoke HttpDefaultPort No AdapterSubscriptionManagement HIEM - Subscribe and Unsubscribe HttpDefaultPort No AdapterNotificationConsumer HIEM - Notify HttpDefaultPort No EntityAuditLogQuery Audit Log Query HttpDefaultPort No EntityDocQuery Document Query HttpDefaultPort No EntityDocRetrieve Document Retrieve HttpDefaultPort No EntitySubjectDiscovery Subject Discovery - Announce, Revoke, and Reidentification HttpDefaultPort No CONNECT_Solaris_Full_Binary_Manual 6 Release 2.1

12 WSDL Services Port SSL EntitySubscriptionManagement HIEM - Subscribe and Unsubscribe HttpDefaultPort No EntityNotificationConsumer HIEM - Notify HttpDefaultPort No NhinAuditLogQuery Audit Log Query 8181 (Glassfish Https Port) Yes NhinSubjectDiscovery Subject Discovery - Announce, Revoke, and Reidentification 8181 (Glassfish Https Port) Yes NhinDocQuery Document Query 8181 (Glassfish Https Port) Yes NhinDocRetrieve Document Retrieve 8181 (Glassfish Https Port) Yes NhinSubscription HIEM - Subscribe, Unsubscribe, and Notify 8181 (Glassfish Https Port) Yes CONNECT_Solaris_Full_Binary_Manual 7 Release 2.1

13 6.0 SOLARIS INSTALL AND CONFIGURATION INSTRUCTIONS 6.1 Install Prerequisite Software on Solaris The prerequisite software needs to be installed on both the Adapter machine and the Gateway machine JDK Installation Obtain a copy of Java JDK 1.6.0_13 from Specify: Platform: Soalris SPARC Language: Multi-language License Agreement Select jdk-6u13-solaris-sparc.sh. Verify execute privilege is set on the shell script. Execute the shell script and follow the instructions. The default location for installation of the JDK is /nhin/jdk. Copy the download to the /nhin/jdk directory to execute the installation GlassFishESB Installation Obtain GlassFishESB installer (glassfishesb-full-installer-solaris-sparc sh) from the Release package. It is located in the zip file NHIN_CONNECT_2.1_Thirdparty_sol10_0707.tar.gz and can be downloaded from the 1. Run the GlassFishESB installer. CONNECT_Solaris_Full_Binary_Manual 8 Release 2.1

14 Figure 6.1-1: Glassfish Welcome Screen 2. Click the Next button. CONNECT_Solaris_Full_Binary_Manual 9 Release 2.1

15 Figure 6.1-2: Glassfish License Agreement 3. Accept the license agreement and click Next. CONNECT_Solaris_Full_Binary_Manual 10 Release 2.1

16 Figure 6.1-3: NetBeans Screen The NetBeans IDE should be installed to /nhin/glassfishesb/netbeans The Java Environment should be set to /nhin/jdk/jdk1.6.0_13 4. Click Next. CONNECT_Solaris_Full_Binary_Manual 11 Release 2.1

17 Figure 6.1-4: Glassfish Screen Glassfish should be installed to /nhin/glassfishesb/glassfish The JDK for glassfish should also be /nhin/jdk/jdk1.6.0_13 The default Admin Username is admin, the default Admin Password is adminadmin. You may use the default values, or enter custom values. CONNECT_Solaris_Full_Binary_Manual 12 Release 2.1

18 It is recommended that the ports be kept at the default values. 5. Click Next and then Install to begin the installation. 6.2 Configuration 1. Change or create the JAVA_HOME environment variable to point to the newly installed Java path located under the /nhin/glassfishesb folder. JAVA_HOME=/nhin/jdk/ jdk1.6.0_13 export JAVA_HOME 2. Change or create the AS_HOME environment variable to point to the Glassfish instance you just created. AS_HOME=/nhin/GlassFishESB/glassfish export AS_HOME 3. Change or create the ANT_HOME environment variable to point to the Ant directory under Netbeans. ANT_HOME=/nhin/GlassFishESB/netbeans/java2/ant export ANT_HOME 4. Update the PATH environment variable to include these installed components. PATH=${JAVA_HOME}/bin:${PATH}:${ANT_HOME}/bin export PATH 5. Change or create the NHINC_PROPERTIES_DIR environment variable to point to the NHINC_PROPERTIES_DIR. This value is configurable, but it is suggested that /nhin/glassfishesb/glassfish/domains/domain1/config/nhin be used. cd /nhin/glassfishesb/glassfish/domains/domain1/config mkdir nhin CONNECT_Solaris_Full_Binary_Manual 13 Release 2.1

19 NHINC_PROPERTIES_DIR=/nhin/GlassFishESB/glassfish/domains/domain1/config/nhin export NHINC_PROPERTIES_DIR NOTE: These environment variables should be stored in the shell resource file for execution on logon. 6. Update the permissions and access to the GlassFishESB directory structure to support runtime access from non-privileged users. cd /nhin chmod R go+rx GlassFishESB cd /nhin/glassfishesb/glassfish/domains/domain1 chmod go+w logs cd /nhin/glassfishesb/glassfish chmod R go+w domains Verify the permissions on the following directories are 777, if they aren t issue a chmod 777 <directory name> on each of those directories: $AS_HOME/jbi $AS_HOME/lib $AS_HOME/addons $AS_HOME/databases $AS_HOME/config $AS_HOME/domains 7. Start the Glassfish application server. Monitor the server.log in $AS_HOME/domains/domain1/logs for status. cd $AS_HOME/bin./asadmin start-domain domain1 cd $AS_HOME/domains/domain1/logs CONNECT_Solaris_Full_Binary_Manual 14 Release 2.1

20 tail f server.log After verifying that glassfish will start successfully (log will say Application server startup complete then shutdown glassfish with the following command and continue with the installation:./asadmin stop-domain domain1 There is a documented issue with NetBeans that requires the installation of all references schemas and wsdls to be available at execution time. The installation of these schemas and wsdls is a work-around for the issue to allow resolution of references. 8. Download these interfaces NHIN_CONNECT_2.1_Interfaces_sol10_0707.tar.gz. cd /nhin cp $HOME/NHIN_CONNECT_2.1_Interfaces_sol10_0707.tar.gz /nhin/. gunzip NHIN_CONNECT_2.1_Interfaces_sol10_0707.tar.gz tar xvf NHIN_CONNECT_2.1_Interfaces_sol10_0707.tar This will place all the required schemas and wsdls in /nhin/projects/nhinc/current/product/production/common/interfaces/src. Updated $AS_HOME/domains/domain1/config/domain.xml file with memory management lines updated the following lines to be these memory values: <jvm-options>-xmx2048m</jvm-options> <jvm-options>-xx:maxpermsize=256m</jvm-options> <jvm-options>-xx:permsize=256m</jvm-options> During initial setup and configuration, additional logging can be enabled by adding the following statements to the domain.xml: <jvm-options>-dcom.sun.xml.ws.transport.http.httpadapter.dump=true</jvm-options> <jvm-options>-dcom.sun.xml.ws.transport.http.client.httptransportpipe.dump=true</jvmoptions> <jvm-options>-djavax.enterprise.resource.xml.webservices.security.level=fine</jvm-options> <jvm-options>-djavax.enterprise.resource.webservices.jaxws=fine</jvm-options> CONNECT_Solaris_Full_Binary_Manual 15 Release 2.1

21 6.2.1 Update Property/Configuration File Settings Gateway.properties This property file contains the main settings for the gateway. Follow the steps outlined below to change this property file. 1. Download the NHIN_CONNECT_2.1_Properties_sol10_0707.tar.gz. cd $AS_HOME/domains/domain1/config/nhin cp $HOME/NHIN_CONNECT_2.1_Properties_sol10_0707.tar.gz. gunzip NHIN_CONNECT_2.1_Properties_sol10_0707.tar.gz tar xvf NHIN_CONNECT_2.1_Properites_sol10_0707.tar su chmod go+w * exit 2. Edit gateway.properties to set the UDDIInquiryEndpointURL to the external IP. 3. Set the localhomecommunityid to the OID from Appendix A. 4. Set the locahomecommunitydescription to a textual description of your environment. 5. Set the localdeviceid to the local Assigning Authority OID. 6.3 Third Party Components Component Catalog This section lists the third party components that are to be added to Glassfish. This catalog is included here for a reference only. These components are included with the release and installation instructions follow. Log4j: Vendor/Publisher: Apache Version: CONNECT_Solaris_Full_Binary_Manual 16 Release 2.1

22 URL: Components: log4j jar Apache Commons Logging: Vendor/Publisher: Apache Version: URL: Components: commons-logging jar Hibernate Relational Persistence for Java: Vendor/Publisher: Hibernate Version: ga URL: Components: antlr jar asm-attrs.jar asm.jar cglib jar commons-collections-2.1.jar dom4j jar ehcache jar hibernate3.jar jdbc2_0-stdext.jar jta.jar c3p jar Metro: CONNECT_Solaris_Full_Binary_Manual 17 Release 2.1

23 Vendor/Publisher: Sun Microsystems Version: 1.4 URL: NHIN Wiki Components: webservices-api.jar webservices-rt.jar webservices-tools.jar MySQL Connector / J (Data base drivers to connect to MySQL DB using Java): Vendor/Publisher: Sun Microsystems Version: 5.0 URL: Components: mysql-connector-java bin.jar XStream: Vendor/Publisher: XStream Version: 1.4 URL: Components: cglib-license.txt cglib-nodep-2.1_3.jar commons-lan-license.txt dom4j jar dom4j-license.txt jdom-1.0.jar jdom-license.txt jettison-1.0-rc2.jar CONNECT_Solaris_Full_Binary_Manual 18 Release 2.1

24 jettison-license.txt joda-time jar joda-time-license.txt junit-license.txt oro-license.txt stax jar stax-api jar wootstox-license.txt wstx-asl jar xml-writer-0.2.jar xom-1.1.jar xom-license.txt xpp3_min-1.1.4c.jar xpp3-license.txt xstream-1.3.jar xstream-benchmark-1.3.jar JDK 1.3 Components were included in the XStream download but should NOT be copied: xalan jar xalan-license.txt xercesimpl jar xerces-license.txt xml-apis jar Spring Framework: Vendor/Publisher: SpringSource Version: CONNECT_Solaris_Full_Binary_Manual 19 Release 2.1

25 URL: Components: spring.jar spring-sources.jar NHIN CONNECT Gateway Components NhincHL7JaxbLib.jar NhincSAMLCallbackLib.jar Installation of Third Party Components This section describes installing required third party components to the existing Glassfish installation. The components described in this section are provided with the release, or may be obtained from their original sources by following the instructions in the next section. The third party components are included in the NHIN_CONNECT_2.1_Thirdparty_sol10_0707.tar.gz. Download the tar and extract the files. cd $HOME gunzip NHIN_CONNECT_2.1_Thirdparty_sol10_0707.tar.gz tar xvf NHIN_CONNECT_2.1_Thirdparty_sol10_0707.tar This will place all the third party products in a $HOME/Thirdparty directory Installation of GNU Tar The installation of Hibernate on Solaris requires use of GNU tar due to long links that are created due to excessive long filenames. If GNU tar is not already installed on the target server, the following steps need to be executed to complete the MySQL installation. NOTE: The following steps are executed as a privileged user (root or other). First determine if GNU tar exists on the target server by pkginfo l grep SMC CONNECT_Solaris_Full_Binary_Manual 20 Release 2.1

26 Some versions of GNU tar get installed as gtar. To check is gtar is installed on your system enter gtar --version If gtar exists, substitute gtar command instead of tar when using GNU tar in the following sections. If GNU Tar is already installed, SMCtar will be included in the list and you can proceed to section 0. Now that it has been verified that the dependent libraries have been installed, install the GNU tar. cd /tmp cp $HOME/Thirdparty/tar-1.21-sol10-sparc-local.gz /tmp/. gunzip tar-1.21-sol10-sparc-local.gz pkgadd d tar-1.21-sol10-sparc-local when prompted use all option Installation of libiconv libraries Execute the pkginfo command to verify libiconv is already installed on the target machine. If the libiconv libraries are already installed, SMCliconv will be included in the list. cd /tmp cp $HOME/Thirdparty/libiconv-1.11-sol10-sparc-local.gz /tmp/. gunzip libiconv-1.11-sol10-sparc-local.gz pkgadd d libiconv-1.11-sol10-sparc-local when prompted use all option Installation of libint libraries Execute pkginfo command to verify if libintl is already installed on the target machine. If the libraries are already installed, SMClintl will be included in the list. CONNECT_Solaris_Full_Binary_Manual 21 Release 2.1

27 cd /tmp cp $HOME/Thirdparty/libintl sol10-sparc-local.gz /tmp/. gunzip libintl sol10-sparc-local.gz pkgadd d libintl sol10-sparc-local when prompted use all option Installation of GCC Libraries Execute pkginfo command to verify if gcc is already installed. If gcc is already installed, SMCgcc will be included in the list. cd /tmp cp $HOME/Thirdparty/libgcc sol10-sparc-local.gz /tmp/. gunzip libgcc sol10-sparc-local.gz pkgadd -d libgcc sol10-sparc-local when prompted use all option Installation of Log4j NOTE: For this installation do not use the tar command, and ensure you download the.zip file. At the time of writing these instructions, the tar.gz file found on the apache download site, has issues with Solaris tar and GNU tar. The following steps are executed as a privileged user. cd /nhin cp $HOME/Thirdparty/apache-log4j zip /nhin unzip apache-log4j Installation of Commons Logging NOTE: For this installation do not use the tar command, and ensure you download the.zip file. At the time of writing these instructions, the tar.gz file found on the apache download site, has issues with Solaris tar and GNU tar. The following steps are executed as a privileged user. cd /nhin CONNECT_Solaris_Full_Binary_Manual 22 Release 2.1

28 cp $HOME/Thirdparty/commons-logging bin.zip unzip commons-logging bin Installation of c3p0 The following steps are executed as a privileged user. cd /nhin cp $HOME/Thirdparty/c3p bin.zip /nhin/. unzip c3p bin.zip Installation of Hibernate This is using the GNU tar installed into /usr/local. The following steps are executed as a privileged user. cd /nhin cp $HOME/Thirdparty/hibernate ga.tar.gz /nhin /usr/local/bin/tar xzvf hibernate ga.tar.gz Installation of copyv3 The installation of copyv3 is only required when running with the default security certificates provided with Glassfish. If you are using certificates and Assigning Authority, this step can be omitted. The following steps are executed as a privileged user. 1. The installation of copyv3 requires Apache Ant. This is using the copy of GNU tar installed previously. cd /nhin cp $HOME/Thirdparty/apache-ant bin.tar.gz /usr/local/bin/tar xzvf apache-ant bin.tar.gz 2. Now install copyv3. cd /nhin CONNECT_Solaris_Full_Binary_Manual 23 Release 2.1

29 cp $HOME/Thirdparty/copyv3.zip /nhin/. unzip copyv3.zip cd copyv3 JAVA_HOME=/nhin/jdk/jdk1.6.0_13 export JAVA_HOME AS_HOME=/nhin/GlassFishESB/glassfish export AS_HOME /nhin/apache-ant-1.7.1/bin/ant After the installation is completed you should be returned to the command prompt. We have experienced the cert installation hang while attempting to start the Appserver; and this requires an interrupt. 3. To verify the installation was successful check the certificate fingerprints. cd $AS_HOME/domains/domain1/config /nhin/jdk/jdk1.6.0_13/bin/keytool -list -keystore cacerts.jks -alias wssip -storepass changeit nhin/jdk/jdk1.6.0_13/bin/keytool -list keystore keystore.jks -alias xws-security-server - storepass changeit Note: If the certificates were installed correctly, you will see something similar to the following responses. Certificate fingerprint (MD5): 1A:0E:E9:69:7D:D0:80:AD:5C:85:47:91:EB:0D:11:B1 Certificate fingerprint (MD5): 1A:0E:E9:69:7D:D0:80:AD:5C:85:47:91:EB:0D:11:B1 If the certificates were not installed correctly, you will see something similar to the following responses. keytool error: java.lang.exception: Alias <wssip> does not exist keytool error: java.lang.exception: Alias <xws-security-server> does not exist 4. To grant access to the CONNECT certificates enter: CONNECT_Solaris_Full_Binary_Manual 24 Release 2.1

30 chmod go+rw *.jks Installation of Metro The following steps are executed as a privileged user. Now install Metro. cd /nhin cp $HOME/Thirdparty/metro-1_4-installer-nightly_02_05_09.jar /nhin/. /nhin/jdk/jdk1.6.0_13/bin/java jar metro-1_4-installer-nightly_02_05_09.jar console At the prompt asking whether to accept the license enter A. cd metro /nhin/apache-ant-1.7.1/bin/ant f metro-on-glassfish.xml install Installation of Connector/J for MySQL The following steps are executed as a privileged user. The GNU tar is used due to long filenames. cd /nhin cp $HOME/Thirdparty/mysql-connector-java tar.gz /nhin/. /usr/local/bin/tar xzvf mysql-connector-java tar.gz Installation of XStream The following steps are executed as a privileged user. cd /nhin cp $HOME/Thirdparty/xstream-distribution bin.zip /nhin/. unzip xstream-distribution-1.3-bin.zip Installation of Spring Framework The following steps are executed as a privileged user. CONNECT_Solaris_Full_Binary_Manual 25 Release 2.1

31 cd /nhin cp $HOME/Thirdparty/spring-framework SEC01-with-docs.zip /nhin/. unzip spring.framework sec01-with-docs.zip Installation of soapui The following steps are executed as a privileged user. cd /nhin cp $HOME/Thirdparty/soapui bin.zip unzip soapui bin.zip cd /nhin/soapui-2.5.1/bin chmod +x soapui.sh cd /nhin chmod R go+w soapui Configure Third Party Components in Glassfish The successful execution of the NHIN CONNECT Gateway requires some of the third party products to be placed in the GlassFishESB/glassfish/lib directory. A script is provided in the release to perform the copy. The Glassfish application server must be stopped during the copy. The application server will then resolve the required references on restart. cd $AS_HOME/bin $HOME/Thirdparty/NHIN_CONNECT_Copy3rdPartyToGFLib.sh./asadmin start-domain domain1 Monitor the $AS_HOME/domains/domain1/logs/server.log for the Application server startup complete or JBI framework startup complete message prior to proceeding. The message you get will depend on whether the http binding component is running or not. CONNECT_Solaris_Full_Binary_Manual 26 Release 2.1

32 6.4 Install and Configure MySQL The Gateway and the reference implementation of the Adapter both use MySQL when a database is necessary. The programmatic access to this database was done using Hibernate. When doing the initial installation of the Gateway and Adapter, it is recommended that MySQL be installed and that the system be verified. After it has been created and verified, other relational databases can be used in place of MySQL by altering the appropriate entries in the hibernate configuration files for those projects which are accessing the database. Directions for configuring hibernate to use other databases is not defined in this document. Set up the database using the following sequence of steps Installation Change the current user to root and add a user and group for mysqld. su groupadd mysql useradd g mysql mysql cd /nhin /usr/local/bin/tar xvf $HOME/Thirdparty/mysql solaris10-sparc-64bit.tar The tar command will create the directory mysql solaris10-sparc-64bit. This directory is owned by root and needs to be owned by mysql. This can be done by executing the following commands as root in the installation directory. Create MySQL data directory and Change the owner ship to mysql user from root cd mysql solaris10-sparc-64bit chown R mysql * chgrp R mysql * scripts/mysql_install_db u mysql Starting and Stopping MySQL To start MySQL make sure you are in MySQL installed directory /nhin/ mysql solaris10-sparc-64bit bin/mysqld_safe u mysql & CONNECT_Solaris_Full_Binary_Manual 27 Release 2.1

33 NOTE: If you run the command as root, you must use the user option as shown. The value of the option is the name of the login account that you created in the step to use for running the server. Since we have not setup and password for root user we are fine to use the above said command. To set up the password for MySQL root user uses the command below: bin/mysqladmin u root password NHIE-Gateway To verify the installation after starting the Server execute few of the following commands: bin/mysqladmin pnhie-gateway version This command will show the complete version history of the MySQL installation and its Solaris Socket file path etc., To stop MySQL Server, make sure you are still using MySQL installed directory path: /nhin/ mysql solaris10-sparc-64bit and execute the command below to Stop the MySQL Server. NOTE: This command is being specified for INFORMATIONAL purposes only. Do NOT execute it at this time. bin/mysqladmin -uroot pnhie-gateway shutdown Configuring MySQL To configure the database schemas and tables associated with the NHIN-CONNECT Gateway, a script is provided named nhincdb.sql file under Thirdparty folder. From the MySQL directory, create a database connection and create the schemas cd /nhin/mysql solaris10-sparc-64bit bin/mysql uroot pnhie-gateway mysql>create DATABASE nhincdb; mysql>\q bin/mysql -uroot -pnhie-gateway nhincdb < $HOME/Thirdparty/dropall.sql bin/mysql -uroot -pnhie-gateway nhincdb < $HOME/Thirdparty/nhincdb.sql This will create Gateway Schemas as listed below: i) aggregator CONNECT_Solaris_Full_Binary_Manual 28 Release 2.1

34 ii) assigningauthoritydb iii) auditrepo iv) docrepository v) patientcorrelationdb vi) subscriptionrepository Try and log into the database as the nhincuser to verify it got created successfully bin/mysql unhincuser pnhincpass If this command fails then issues the following commands: bin/mysql uroot pnhie-gateway mysql> CREATE USER localhost IDENTIFIED BY nhincpass ; mysql> GRANT ALL PRIVILEGES ON *.* TO localhost WITH GRANT OPTION; mysql> quit Try to log in as nhincuser again: bin/mysql unhincuser pnhincpass 7.0 SSL CERTIFICATE REQUEST AND INSTALLATION PROCESS This section outlines how to add 2-way SSL to an existing working system, such as the NHIN CONNECT Gateway. To use 2-way SSL, there are two components needed. First, the server must present a certificate identifying itself to the consumer of its services. This server certificate must match (the server portion of the URL or the service must be the same as the name on the certificate) and must be trusted (accomplished by having the issuer of the certificate as a trusted root certificate authority on the client). Second, the client must send a certificate to the server to identify itself. This client certificate must be trusted by the server (by having the trusted root certificate on the server) (there does not appear to be any validation of the client cert to ensure that it came from a certain address). Glassfish comes with a default keystore to use for presenting the server certificate. Instead of using the default keystore, a new keystore will be created, which will hold a certificate issued by the trusted root authority - NHIN-CN. Glassfish also comes with a default trust store used to validate remote certificates - in this case, to determine if it trusts the client cert. NOTE: This section only applies to the NHIN CONNECT Gateway machine. This section is not applicable to the NHIN CONNECT Adapter machine. CONNECT_Solaris_Full_Binary_Manual 29 Release 2.1

35 7.1 Setup 1. Note: ensure that ports are opened on the firewall to allow traffic to the server. The NHINC gateway uses ports 8080 and 9080 for HTTP traffic (this is used for the entity interface) and ports 8181 and 9081 for HTTPS traffic (this is used for the NHIE interfaces). 7.2 Generate Certificate Request 2. Create a new working "certificate request" directory (i.e., /nhin/glassfishesb/certificaterequests). 3. Open a command prompt to the "certificate request" directory. 4. Create the new keystore by running the following command: /nhin/jdk/jdk1.6.0_13/bin/keytool - genkeypair -keyalg RSA -keysize keystore gateway.jks -keypass xxxxxxxx -storepass xxxxxxxx -validity 365 -alias gateway -dname " [email protected], cn=testgateway.fedsconnect.org, OU=Testing, O=YourOrganization, L=YourCity, S=YourState, C=US" Note on parameters: -keystore: This is the name of the java keystore that will be created. This can be modified if desired. -keypass -storepass: This sets the passwords for the store and the request. Replace xxxxxxxx with your password. The keystore and store passwords should be the same. -dname: o o o o o o Address: address for the point of contact for your network. CN: This domain must match the domain of the address of the services. Replace testgateway.fedsconnect.org with the name of your gateway. OU: Organizational Unit aspect of the name. O: Replace YourOrganization with the name of your organization. L: Replace YourCity with the city your server is hosted in. S: Replace YourState with the state your server is hosted in. 5. Create a request for the certificate by running the following command (the request must be made from the server that will use the request): CONNECT_Solaris_Full_Binary_Manual 30 Release 2.1

36 /nhin/jdk/jdk1.6.0_13/bin/keytool -certreq -alias gateway -sigalg SHA1withRSA - keystore gateway.jks -storepass xxxxxxxx -file testgateway.fedsconnect.org.csr Note on the parameters: -alias: This sets a name that will refer to this cert. This can be change if desired. -keystore: This must be the same name as the keystore created above. -storepass: This must be the same as the password specified when creating the keystore -file: This is the filename of the certificate request. This can be changed if desired. NOTE: Use of the file option has caused some certificate requests to have imbedded CR/LF. If the certificate authority reports this anomaly in your request, remove the file option and grab the output and paste into a file manually. 7.3 Download Root Certificate 6. Download the Root Certificate, onc_ca.arm from the NHIN Certificate Authority at o The browser will display a page with text. Copy all of the text until the line that contains this text: -----END CERTIFICATE----- o Open a new text document in your Certificate Request directory. Copy the paste into this text document. Ensure there are no extra spaces after the text: -----END CERTIFICATE----- o Save the file as onc_ca.arm. 7.4 Send Certificate request Upload the generated certificate request (*.csr) to the certificate authority (currently, ). It normally takes one working day for the request to be signed. The signed certificate can be downloaded here: Install the certificate Update the keystore with the response. This will update the server certificate in the keystore to have an issuer of nhin-cn. Save these files to your working "certificate request" directory. Import the certificate authority certificate into the keystore. This is the certificate that was downloaded in step 6.3 above. /nhin/jdk/jdk1.6.0_13/bin/keytool -import -v -trustcacerts -alias onc_ca -file onc_ca.arm - keystore gateway.jks CONNECT_Solaris_Full_Binary_Manual 31 Release 2.1

37 When prompted, enter the password for your keystore. Note on the parameters: -alias: This is how the alias for the certificate authority. This can be modified if desired. -file: This points to the certificate authority file (*.arm) file. It is not expected that this will vary. -keystore: This must point to the keystore used in the request. When prompted with Trust this certificate? [no]: enter yes. Import the server certificate into the keystore. /nhin/jdk/jdk1.6.0_13/bin/keytool -import -v -alias gateway -file fedcrsp.arm -keystore gateway.jks When prompted, enter the password for your keystore. Note on the parameters: -alias: This must match the alias given during the creation of the request -file: This points to the certificate request response file (*.arm) file. This is the file received from the certificate authority. -keystore: This must point to the keystore used in the request. Locate the trusted root authority store. By default, this store will be located in: <glassfish>/domains/<domain directory>/config/cacerts.jks. It is advisable to backup the cacerts.jks file at this time. Import the trusted root certificate into the trusted root authority store. /nhin/jdk/jdk1.6.0_13/bin/keytool -import -v -trustcacerts -alias onc_ca -file onc_ca.arm - keystore <path>/cacerts.jks When prompted with Trust this certification? [no] enter yes. Note on the parameters: -alias: This is how the alias for the certificate authority. This can be modified if desired. -file: This points to the certificate authority file (*.arm) file. It is not expected that this will vary. -keystore: This must point to the certificate authority store. You will be prompted for a password. The default glassfish password is changeit. If you have changed this value, use the updated value instead. CONNECT_Solaris_Full_Binary_Manual 32 Release 2.1

38 Validate the certificates were imported correctly by viewing the store. You will be prompted for the passwords after each execution of the keytool utility. /nhin/jdk/jdk1.6.0_13/bin/keytool -list -v -alias gateway -keystore gateway.jks /nhin/jdk/jdk1.6.0_13/bin/keytool -list -v -alias onc_ca -keystore gateway.jks /nhin/jdk/jdk1.6.0_13/bin/keytool -list -v -alias onc_ca -keystore <path>/cacerts.jks This should output each of the certificates. If the certificate was not imported, there will be an error from the keytool. Copy the keystore (gateway.jks) to the domain's config directory (<glassfish>/domains/<domain directory>/config/). Open the domain configuration file for editing. (<glassfish>/domains/<domain directory>/config/domain.xml). (Alternately, these changes can be made by using the admin console) Update the domain configuration to point to the new keystore and supply the password (the password option is not in the original configuration). To do this, replace: to <jvm-options>- Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/config/keystore.jks</jvmoptions> <jvm-options>- Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/config/gateway.jks</jvmoptions> <jvm-options>-djavax.net.ssl.keystorepassword=xxxxxxxx</jvm-options> Replace xxxxxxxx with the password you created above. Update the domain configuration to use the new server certificate. To do this, replace all instances of "s1as" with the updated certificate alias ("gateway"). In our default server, there were 12 instances of the certificate alias to update. Enable two-way SSL. This is done by adding the following: <jvm-options>-dcom.sun.jbi.httpbc.enableclientauth=true</jvm-options> 8.0 NHIN-CONNECT SERVER CONFIGURATION Configuration settings for the Gateway are predominately platform independent. Any platform specific items are explicitly stated. The settings listed below need to be applied to both the Adapter machine and the Gateway machine. CONNECT_Solaris_Full_Binary_Manual 33 Release 2.1

39 8.1 Configuration Settings Metro 1.4 Installation Settings Update $AS_HOME/domains/domain1/config/domain.xml file. Add the following lines to deal with the certificate and other items in domain.xml toward the end of the file within the existing block of <jvm-options> tags: <!-- HTTP Upgrade to support 2 way SSL --> <jvm-options>-dcom.sun.jbi.httpbc.enableclientauth=true</jvm-options> <jvm-options>- Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/config/gateway.jks</jvmoptions> <jvm-options>-djavax.net.ssl.keystorepassword=xxxxx</jvm-options> <jvm-options>- Djavax.net.ssl.trustStore=${com.sun.aas.instanceRoot}/config/cacerts.jks</jvmoptions> <jvm-options>-djavax.net.ssl.truststorepassword=changeit</jvm-options> <jvm-options>-dserver_key_alias=gateway</jvm-options> <jvm-options>-dclient_key_alias=gateway</jvm-options> NOTE: The KeyStore password will be the same keystore password generated in the certificate request Glassfish Application Variables NhincHttpPort is used to identify the default Glassfish Http port so Composite Applications can communicate with EJBs. This value is customizable. The recommended setting is It must match the default http port selected when installing glassfish. The value can be set through the Glassfish Admin Console. To set, you will need to first log on to the glassfish admin console. Open the URL The default user name is admin and the default password is admin/adminadmin. If you customized any of these settings in your installation, use your custom settings instead. During some installations of Glassfish, the sun-http-binding component initializes in the stopped state. The sun-http-binding component needs to be running to assign the Application Variable. 1. From the main page, select JBI Components sun-http-binding 2. Verify that the sun-http-binding component is started. If not, select the Start button on the sun-http-binding Binding Component General Properties page. 3. From the sun-http-binding page, select Application Variables 4. Click the Add Variable button. Variable type is Number, and the desired value (8080 is recommended). The variable name is NhincHttpPort. CONNECT_Solaris_Full_Binary_Manual 34 Release 2.1

40 Figure 8.1-1: Manage Application Variables 8.2 Connection Management This section is provided for documentation purposes only. This section will guide the user through any configuration changes needed. The NHIN Service Registry is responsible for managing connections in the NHIN CONNECT gateway. There are two places that connection information is configured. First, the NHIN UDDI registry is managed by the NHIN and contains connection information for the other NHIN members. A service runs under glassfish called the UDDI Update Manager which periodically queries the NHIN UDDI Service Registry and retrieves the current connection information. This information is placed in the uddiconnectioninfo.xml file which is located in the $NHINC_PROPERTIES_DIR. This file should not be changed by hand. Any changes made by hand to this file will be overwritten the next time the UDDI Update Manager queries the NHIN UDDI service registry. In addition, an internal connection XML file may also be configured to override the settings obtained from the NHIN UDDI server. It is also used to contain connection information that is internal to the NHIN CONNECT software (e.g. Not published to the NHIN). This file is called CONNECT_Solaris_Full_Binary_Manual 35 Release 2.1

41 internalconnectioninfo.xml and is also located in the $NHINC_PROPERTIES_DIR. Endpoint URL connection information in this file will take precedence over the connection information in the uddiconnectioninfo.xml file. If there is a setting in both places for the same service and home community ID, then the one in the internalconnectioninfo.xml file will be used. One additional configuration file is needed during connection management. It is called, connectionepr.properties. This file contains information about each service that is necessary when dynamically changing the endpoint URL for a service. This file should not be changed. It is the same for every NHIN CONNECT site. Changing any of the settings in this file could cause the NHIN CONNECT software to fail. The NHIN CONNECT connection management services monitor the last-modified timestamp on both the uddiconnectioninfo.xml and the internalconnectioninfo.xml file. If a change is made to either file, the new connection information is automatically used. You do not need to restart glassfish after making a change to the internalconnectioninfo.xml file or when the UDDI Update Manager updates the uddiconnectioninfo.xml file. There are a handful of properties in the gateway.properties file that are used to configure the NHIN CONNECT for communicating with the NHIN UDDI Service Registry. The following are settings you will see: UDDIInquiryEndpointURL: This is the endpoint URL for the UDDI Service Registry Inquiry service. Currently this should be set to: if your gateway is outside of the DMZ and if it is within the DMZ, then it should be set to: UDDIBusinessesToIgnore: This contains a list of services, separated by semicolons that are defined in the UDDI Service Registry which should be ignored and not considered as real connections. Currently this should be set to the following string: uddi:replication:findbusiness;uddi:replication:findtmodels;uddi:nhinregistry:node UDDIRefreshDuration: This is the number of seconds between the time the UDDI Update Manager queries the NHIN UDDI Service Registry and re-creates the uddiconnectioninfo.xml file. UDDIRefreshKeepBackups: If set to true, then when the uddiconnectioninfo.xml file is updated, a backup is made by renaming the current file and appending the date and time. If set to false, then no back up is maintained. InternalConnectionRefreshDuration: This property is currently not in use. InternalConnectionRefreshKeepBackups: This property is currently not in use InternalConnectionInfo.xml File The internalconnectioninfo.xml file can be used to override settings obtained by the NHIN UDDI Service Registry as well as to configure endpoints that are internal to NHIN CONNECT CONNECT_Solaris_Full_Binary_Manual 36 Release 2.1

42 and not published to the NHIN. This section describes the format of this file. The following is a sample of the internal connectioninfo.xml file. <InternalConnectionInfos> <!-- This should contain one or more internalconnectioninfo sections one per home community --> <internalconnectioninfo> <homecommunityid> </homecommunityid> <name>va</name> <description>va</description> <services> <!-- You can define one or more services --> <service> <name>subjectdiscovery</name> <description>nhin CONNECT Subject Discovery Service</description> <endpointurl> y</endpointurl> </service> </services> </internalconnectioninfo> <internalconnectioninfo> <homecommunityid> </homecommunityid> <name>dod</name> <description>dod</description> <services> <service> <name>subjectdiscovery</name> <description>nhin-connect Subject Discovery Service</description> <endpointurl> ry</endpointurl> </service> <service> <name>notificationconsumer</name> <description>nhin CONNECT HIEM Notify Service</description> <endpointurl> </endpointurl> </service> </services> </internalconnectioninfo> </InternalConnectionInfos> When connection manager determines a connection endpoint, it uses the value in the <service>/<name> tag along with the value in the <homecommunityid> tag. Note that if you are overriding a service from the uddiconnectioninfo.xml file, the <service>/<name> should be identical to the <uniformservicename> in the uddiconnectioninfo.xml file. Also note that the <internalconnectioninfo>/<name> and <internalconnectioninfo>/<description> does NOT override settings for these fields in the uddiconnectioninfo.xml file. The only overrides that occur are the service level connection information. CONNECT_Solaris_Full_Binary_Manual 37 Release 2.1

43 The internalconnectioninfo.xml file is located in the $NHINC_PROPERTIES_DIR defined earlier in this section. 8.3 Reidentification.xml This file is used on the adapter to keep the mappings between a patient pseudonym and its corresponding real patient identifier. The reidentification.xml file is located in the $NHINC_PROPERTIES_DIR defined earlier in this section. 8.4 Gateway Properties The gateway properties are defined in the following file: $NHINC_PROPERTIES_DIR/gateway.properties The settings include: CacheRefreshDuration: This is used to determine how often the property information is cached. Setting it to 0, means that it is not cached and is re-read every time the property is accessed. Setting it to -1, or omitting this property means that it is cached indefinitely (until Glassfish is restarted), and setting it to a value > 0 is the number of seconds that the cache is kept in memory. localhomecommunityid: The local home community OID for a particular instance of the NHIN CONNECT Gateway. localhomecommunitydescription: The local home community description for a particular instance of the NHIN CONNECT Gateway. localdeviceid: The local home community s assigning authority OID for a particular instance of the NHIN CONNECT Gateway. servicedocumentquery: This flag indicates if this instance of the NHIN CONNECT Gateway should service document query requests. documentquerypassthrough: This flag indicates if this instance of the NHIN CONNECT Gateway should pass document query requests directly to the Adapter Interface. documentqueryqueryself: This flag is used to indicate if a document query should be performed on our own gateway. If the flag is set to false, only remote gateways are queried. If set to true, our own gateway is queried along with the remote gateways. CONNECT_Solaris_Full_Binary_Manual 38 Release 2.1

44 servicedocumentretrieve: This flag indicates if the instance of the NHIN CONNECT Gateway should service document retrieve requests. documentretrievepassthrough: This flag indicates if this instance of the NHIN CONNECT Gateway should pass document retrieve requests directly to the Adapter Interface. servicesubjectdiscovery: This flag indicates if the instance of the NHIN CONNECT Gateway should service subject discovery requests. subjectdiscoverypassthrough: This flag indicates if this instance of the NHIN CONNECT Gateway should pass subject discovery requests directly to the Adapter Interface. serviceauditrepository: This flag indicates if the instance of the NHIN CONNECT Gateway should service audit log/query requests. auditrepositorypassthrough: This flag indicates if this instance of the NHIN CONNECT Gateway should pass audit query requests directly to the Adapter Interface. servicesubscription: This flag indicates if the instance of the NHIN CONNECT Gateway should service HIEM subscribe and unsubscribe requests. subscriptionpassthrough: This flag indicates if this instance of the NHIN CONNECT Gateway should pass HIEM subscribe and unsubscribe requests directly to the Adapter Interface. servicenotify: This flag indicates if the instance of the NHIN CONNECT Gateway should service HIEM notify requests. notifypassthrough: This flag indicates if this instance of the NHIN CONNECT Gateway should pass HIEM notify requests directly to the Adapter Interface. aggregatorgarbagecollectiontimeduration: This is the duration in seconds of the time between garbage collection threads that are run on the aggregation database. Garbage collection cleans up stale aggregator transactions so that the database is selfmaintaining. aggregatorgarbagecollectionstaleduration: This is the amount of time in seconds that must pass before an aggregator transaction is considered stale and available for garbage collection. CONNECT_Solaris_Full_Binary_Manual 39 Release 2.1

45 NotificationConsumerEndpointAddress: The value stored with this property is included in a subscription message when the local gateway creates a document subscription message that is sent to a remote gateway. This value is included to indicate where the remote gateway should send documents that correspond to the document subscription. NotificationConsumerService/HiemNotify is a sample value. subscription.repository.implementation.class: This property defines the type of subscription repository used. Initially, only a file based repository is supported and the value of gov.hhs.fha.nhinc.subscription.repository.service.filesubscriptionrepository is required. This property will allow changing the type of repository to a different type like a database if that is supported at a future date. subscription.repository.file.name: This property is used if the subscription.repository.implementation.class is a file based subscription repository. The file name used by the subscription repository if document subscriptions are stored in the file system. If the value of subscriptionlist.xml is entered for this property, the subscription repository as a file will be stored in the config directory of the Glassfish domain. On a Windows operating system, the given entry would result in the file C:\GlassfishESB\glassfish\domains\domain1\config\ subscriptionlist.xml being created and used as the subscription repository. UDDIInquiryEndpointURL: This is the endpoint URL for the UDDI Service Registry Inquiry service. Currently this should be set to: if your gateway is outside of the DMZ and if it is within the DMZ, then it should be set to: UDDIBusinessesToIgnore: This contains a list of services, separated by semicolons that are defined in the UDDI Service Registry which should be ignored and not considered as real connections. Currently this should be set to the following string: uddi:replication:findbusiness;uddi:replication:findtmodels;uddi:nhinregistry:node UDDIRefreshDuration: This is the number of seconds between the time the UDDI Update Manager queries the NHIN UDDI Service Registry and re-creates the uddiconnectioninfo.xml file. UDDIRefreshKeepBackups: If set to true, then when the uddiconnectioninfo.xml file is updated, a backup is made by renaming the current file and appending the date and time. If set to false, then no back up is maintained. InternalConnectionRefreshDuration: This property is currently not in use. InternalConnectionRefreshKeepBackups: This property is currently not in use. PdpEntityName: Determines which PDP the Policy Engine will use. Options are: ConnectOpenSSO or Jericho. The default value is ConnectOpenSSO. CONNECT_Solaris_Full_Binary_Manual 40 Release 2.1

46 8.5 Adapter Properties The adapter.properties file is used to hold reference adapter specific properties. This file should be located in: $NHINC_PROPERTIES_DIR. XDSbHomeCommunityId: This setting specifies the home community ID for the document registry/repository associated with this adapter EntityNotificationConsumerURL: This is the URL for the Gateway s Entity HIEM Notify service. assigningauthorityid: This is the local assigning authority id. 8.6 Connection EPR Properties The connectionepr.properties is used with the new Connection Manager. Please note that you should not change the contents of this file. This file is maintained in coordination with the NHIN CONNECT software. A description of the contents is placed here for information purposes. The new connection manager is the one that implements the NHINC Service Registry that will enable connection information to be maintained by a UDDI server. During the implementation of this, additional methods were added to simplify the ability to get endpoints that can be used by Glassfish to do dynamic endpoints. This property file contains properties that were previously hard coded when doing dynamic endpoints. For each WSDL that is used with dynamic endpoints, the following set of properties need to be defined. The properties will be defined with the following format: <UniformServiceName>.<Property>=<value>. Where <UniformServiceName> is the name defined in the UDDI server for that service, <Property> is the name of the property, and <Value> is the value to be used for that property. The following is a list of all of the <Property> settings that should be in the file. NameSpaceURI: The URI for the namespace for the WSDL. PortName: The port name defined for this WSDL. ServiceName: The service name defined for this WSDL. NamespacePrefix: The name space prefix defined for this WSDL. The connectionepr properties are defined in the following file: $NHINC_PROPERTIES_DIR/connectionEPR.properties 8.7 Component Proxy Spring Configuration properties There is a collection of configuration files that are used by Spring to determine how the messaging proxy projects communicate. These files are located in $NHINC_PROPERTIES_DIR and follow the following naming convention: <Component Name>ProxyConfig.xml. Below is an example of one of these files. In order to switch out implementations just replace with class name specified with the desired implementation class. CONNECT_Solaris_Full_Binary_Manual 41 Release 2.1

47 <beans xmlns=" xmlns:xsi= xsi:schemalocation=" <!-- Web-service MPI implementation --> <bean id="mpi" class="gov.hhs.fha.nhinc.mpi.proxy.adaptermpiwebserviceproxy"/> </beans> 8.8 HIEM Topic Configuration Properties This properties file contains information needed to process HIEM topics. This file needs to be located in $NHINC_PROPERTIES_DIR and is called hiemtopicconfiguration.xml. Below is an example of the contents within this file. <topicconfigurations> <topicconfiguration> <topic><![cdata[ <wsnt:topic xmlns:wsnt=" xmlns:nhin=" Dialect=" 1/TopicExpression/Simple" >nhin:someothertopic1</wsnt:topic> ]]></topic> <issupported>true</issupported> <ispatientcentric>false</ispatientcentric> <ispatientrequired>false</ispatientrequired> <patientidentifiersubscribelocation>test subscribe location</patientidentifiersubscribelocation> <patientidentifiernotifylocation>test notify location 1</patientIdentifierNotifyLocation> <patientidentifierformat>hl7encoded</patientidentifierformat> </topicconfiguration> </topicconfigurations> 9.0 DEPLOYMENT The Adapter and Gateway components are included in NHIN_CONNECT_2.1_Gateway_sol10_0707.tar.gz. Download this file and extract the contents. This will create a NHINC_Binaries directory which contains all the components. cd $HOME gunzip NHIN_CONNECT_2.1_Gateway_sol10_0707.tar.gz tar xvf NHIN_CONNECT_2.1_Gateway_sol10_0707.tar CONNECT_Solaris_Full_Binary_Manual 42 Release 2.1

48 9.1 Deploying applications to Glassfish This section describes how deploy the NHIN-CONNECT applications to the Glassfish servers Adapter Components. The following applications must be deployed as part of the Adapter: Filename AdapterReidentficationEJB.jar Application Type EJB AdapterPoliceyEngineTransformEJB.jar AdapterPIPEJB.jar AdapterPEPEJB.jar EJB EJB EJB AdapterPolicyEngineOrchestratorEJB.jar EJB AdapterMpiEJB.jar EJB MpiManagerEJB.jar EJB MpiEJB.jar EJB AdapterCA.zip CA DocumentRepositoryEJB.jar EJB Each of the applications above will be deployed via the Glassfish admin console Gateway Components The following applications must be deployed as part of the Gateway: AggregatorEJB.jar Filename Application Type EJB CONNECT_Solaris_Full_Binary_Manual 43 Release 2.1

49 Filename AuditRepositoryEJB.jar Application Type EJB AuditLogEJB.jar ConnectionManagerEJB.jar EJB EJB DocumentTransformEJB.jar EJB EntityAuditLogQueryEJB.jar EJB EntityHiemSubscriptionEJB.jar EJB GatewaySubscriptionRepositoryEJB.jar EJB GatewayPolicyEngineFacadeEJB.jar EJB GatewayPolicyEngineTransformationEjb.jar EJB NhincAuditLogDteEJB.jar EJB NhincAuditQueryEJB.jar EJB NhincDocQueryEJB.jar EJB NhincDocRetrieveEJB.jar EJB NhincHiemSubscriptionEJB.jar EJB NhincSubDiscDataTransformEJB.jar EJB NhincSubjectDiscoveryEJB.jar EJB CONNECT_Solaris_Full_Binary_Manual 44 Release 2.1

50 Filename PatientCorrelationEJB.jar Application Type EJB PatientCorrelationFacadeDTEEjb.jar EJB PropAccessorEJB.jar EJB SubscriptionDteEjb.jar EJB UDDIUpdateManagerEJB.jar EJB Note: this does not get automatically deployed in the script, must deploy manually if desired. EntityCA.zip CA NhinCA.zip CA Update Glassfish lib cp $HOME/NHINC_Binaries/NhincSAMLCallbackLib.jar $AS_HOME/lib cp $HOME/NHINC_Binaries/NhincHL7JaxbLib.jar $AS_HOME/lib Verify that these jars are owned by your current user. If not, perform the following steps: su chown <currentuser> $AS_HOME/lib/NhincSAMLCallbackLib.jar chgrp <currentuser> $AS_HOME/lib/NhincSAMLCallbackLib.jar chown <currentuser> $AS_HOME/lib/NhincHL7JaxbLib.jar chgrp <currentuser> $AS_HOME/lib/NhincHL7JaxbLib.jar Restart the Glassfish application server. CONNECT_Solaris_Full_Binary_Manual 45 Release 2.1

51 cd $AS_HOME/bin./asadmin stop-domain domain1./asadmin start-domain domain Deployment of CONNECT Deployment on Solaris deploys both the Adapter and Gateway on a single machine. Scripts are provided in the NHIN_CONNECT_2.1_Gateway_sol10_0707.tar.gz. The following sections describe how to deploy for the different configurations. During the deployment, there will be several expecting WARNING messages in the server.log. These are a few of the expected warnings. <timestamp> WARNING sun-appserver2.1 datatypes-base.xsd warning: p-props-correct- 2.2: maxoccurs must be greater than or equal to 1. #] <timestamp> WARNING sun-appserver2.1 FromXmlParser.endElement(): Found unrecognized end element </sxed:editor>, namespace= SUNExtension/Editor #] Deployment of the Adapter and Gateway to Single Machine Deployment of the Adapter and Gateway components on a single machine required the Glassfish Application Server to be running. Monitoring the server.log file is required to verify successful deployment. $AS_HOME/bin/asadmin start-domain domain1 Monitor $AS_HOME/domains/domain1/logs/server.log for JBI framework startup complete message. $HOME/NHINC_Binaries/DeployAllBinaries.sh Monitor $AS_HOME/domains/domain1/logs/server.log for any exceptions. 9.2 Configuration Files This section describes the configuration files that are needed by Glassfish in order to run the NHIN CONNECT Gateway. Edit $AS_HOME/domains/domain1/domain.xml. Within the section of <jvm-options> tags, enter the following configuration item to ensure that log4j.properties file is referenced by Glassfish CONNECT_Solaris_Full_Binary_Manual 46 Release 2.1

52 <jvm-options>- Dlog4j.configuration=file:$AS_HOME/domains/domain1/config/log4j.properties</jvm-options> To help limit the amount of log messages generated by c3p0 during access to the MySQL database, edit the $NHINC_PROPERTIES_DIR/log4j.properties file to add the following line: log4j.appender.com.mchange.v2.c3p0=warn Copy the properties file into the Glassfish configuration directory for access at runtime. cp $NHINC_PROPERTIES_DIR/log4j.properties $AS_HOME/domains/domain1/config/. This completes the installation and configuration of the NHIN CONNECT Gateway System. The next step for the installer is to verify the installation. Run the Soap UI Self Tests to ensure the installation was successful. NOTE: We have experienced the soapui default installation has the setting for the HTTP Version set incorrectly. If you experience any connectivity issues executing the soapui tests, verify that the HTTP Version is set to 1.1 from the dropdown from File->Preferences HTTP Settings tab. This is a known runtime WARNING message that is generated that can be ignored. The message is similar to # T11:36: WARNING sunappserver9.1 javax.enterprise.system.stream.err _ThreadID=52;_ThreadName=BPELSEInOut Thread4;Process Instance Id= :-165ac5b7: bc08:-7fdf;Service Assembly Name=EntityCA;BPEL Process Name=PatientCorrelationFacadeBpel;_RequestID=132b49c0- e2f4-42cc-80f8-1e95317dcbbf; java.util.logging.errormanager: 5: Error in extracting Name Value Pairs #] [# T11:36: WARNING sunappserver9.1 javax.enterprise.system.stream.err _ThreadID=52;_ThreadName=BPELSEInOut Thread4;Process Instance Id= :-165ac5b7: bc08:-7fdf;Service Assembly Name=EntityCA;BPEL Process Name=PatientCorrelationFacadeBpel;_RequestID=132b49c0- e2f4-42cc-80f8-1e95317dcbbf; java.lang.nullpointerexception CONNECT_Solaris_Full_Binary_Manual 47 Release 2.1

53 10.0 ACRONYMS CA CAC CD CDC CMS DAT DOD DURSA DVD EHR EMR ESB FHA GB HDD HITSP IDE IHS Certificate Authority Common Access Card Compact Disk Centers for Disease Control & Prevention Centers for Medicare & Medicaid Services Digital Audio Tape Department of Defense Data Use and Reciprocal Support Agreement Digital Video Disc Electronic Health Record Electronic Medical Record Enterprise Service Bus Federal Health Architecture Gigabyte Hard Disk Drive Healthcare Information Technology Standards Panel Integrated Drive Electronics Indian Health Services IPv6 Internet Protocol Version 6 MB MPI NCI NDMS NHIE NHIN NIST OID ONC OS QA Megabyte Master Patient Index National Cancer Institute National Disaster Medical System NHIN Health Information Exchange Nationwide Health Information Network National Institute of Standards and Technology Object Identifier or Home Community ID Office of the National Coordinator Operating System Quality Assurance CONNECT_Solaris_Full_Binary_Manual 48 Release 2.1

54 RAID RAM SCSI SDK SSA SSL TBD USB VA Redundant Array of Inexpensive Disks Random Access Memory Small Computer System Interface Software Development Kit Social Security Administration Secure Sockets Layer To Be Determined Universal Serial Bus Department of Veterans Affairs CONNECT_Solaris_Full_Binary_Manual 49 Release 2.1

55 APPENDIX A CONNECT_Solaris_Full_Binary_Manual A-1 Release 2.1

56 A. OID REQUEST SUBMITTAL PROCESS A.1 Getting Started Before you can request the OID, there are a few questions that you should answer. These answers will be requested during the OID request process. Your Main Point of Contact (POC): (This can be a project manager or a Technical point of contact) Your POC s office address: Your POC s phone number: Your POC s fax number: Your POC s Title: Organization s url: A.2 Submitting the Request 1. Login into: Figure A.2-1: HL7-OID Registration Home Page CONNECT_Solaris_Full_Binary_Manual A-2 Release 2.1

57 2. Select the Click to Obtain or Register an OID Hyperlink. Figure A.2-2: Complete Contact Information 3. Complete the form as shown above including the information collected from Section A.1 of this document a. The POC from section A.1 is your Contact Person and Responsible Body. It may also be the Submitter but the individuals do not have to be the same person. b. Please make sure to add prior to the url information otherwise the OID request will error. c. Resp Body Type select Government body from the drop down. d. Once all the pertinent information is entered select the Continue button. CONNECT_Solaris_Full_Binary_Manual A-3 Release 2.1

58 Figure A.2-3: Select type of OID 4. Leave the default as shown and select the Next button. CONNECT_Solaris_Full_Binary_Manual A-4 Release 2.1

59 Figure A.2-4: New or Existing OID Designation 5. Select the first radio button and then select the Next button. Figure A.2-5: HL7 OID Description 6. Add the Submitter contact information, enter the name of the server and provide a minor description. a. Please note that the user can search by Object Description to locate the OID information. So you may want to provide a description that is significant to your organization. b. Type of OID= 3. c. Select the Request my OID button. CONNECT_Solaris_Full_Binary_Manual A-5 Release 2.1

60 Figure A.2-6: OID Registration Confirmation 7. An acknowledgement of the submittal is displayed on the screen with the OID that as been generated. Please make note of the OID. Select the Back button to return to the first screen. Figure A.2-7: OID Confirmation CONNECT_Solaris_Full_Binary_Manual A-6 Release 2.1

61 8. An detailing the request will also be sent to the Submitter and the Responsible Body. CONNECT_Solaris_Full_Binary_Manual A-7 Release 2.1

62 A.3 Searching for an OID on the site Figure A.3-1: Searching by OID number 1. The user can search by the OID number. The OID number that was generated or registered on this site is entered in the left panel in the Enter the OID: box and then the Find OID is selected. The right hand panel will display a drop down with results that match the criteria entered. The user can then select from the drop down the desired results and the Submit button for the details. a. Please note that if the OID that you seek is not in the drop down, it may not have been registered or obtained from this site. CONNECT_Solaris_Full_Binary_Manual A-8 Release 2.1

63 Figure A.3-2: Search by OID Description 2. The user can search by the OID description. The OID description that was entered during the generation process on this site is entered in the left panel in the Enter a string to search the OID description: box, and then the Find OID is selected. The right hand panel will display a drop down with results that match the criteria entered. The user can then select from the drop down the desired results and the Submit button for the details. CONNECT_Solaris_Full_Binary_Manual A-9 Release 2.1