Local Installation Guide

This document outlines the steps required to create a local installation for the Edge Testing Tool. This involves setting up at least three servers at this point due to the fact that the components in the architecture use the standard port 25 (in addition to a few other ports). The main server is the Edge server that runs the main application packaged as a springboot jar. This also hosts the XDS toolkit and a Name server which require tomcat containers. The second server is for running the SMTP service - Apache James is being used. The ccda-validator is also hosted in this server. The third server runs the Direct RI (java). A different reorganization is possible, and will need adjustments to the configuration.

Edge server installation steps

Prerequisites:

Java 8 openjdk (installation steps Appendix A)
Tomcat 7 (installation steps Appendix B).
Mysql database (installation steps Appendix C).
Name server (installation steps Appendix D).

Installation.

Step 1. Navigate to the ETT's downloadable and executable .jar file (ett.jar) located in the directory located here. The needed configuration information (contained within the application properties file) is here.

     # create /opt/ttp/logs (-p for parents create, if not present)
     # also, opt is the parent directory; but if you choose a different dir, configure ttpservice accordingly
     sudo mkdir -p /opt/ttp/logs
     sudo cp downloaded-ett.jar /opt/ttp/ttp.jar
     sudo cp downloaded-application.properties /opt/ttp
     sudo cp downloaded-ttpservice /etc/init.d    
     sudo chmod u+x /etc/init.d/ttpservice

Step 2. Installing Local XDSTOOLS Instance.

The ETT depends on a version of XDSTOOLS for its XD* related components. The user can either point the configuration file to the public copy available online (see the default instructions) or can point to a copy running on their local system.

Download the most recent version of xdstools?.war from the following link: [xdstools] (https://github.com/usnistgov/iheos-toolkit2/releases). This is a web archive that will need to be deployed from a local Tomcat instance.

mkdir -p [tomcat-dir]/toolkit/external_cache/environment/NA2015
Unzip keyAndCert.zip into [tomcat-dir]/toolkit/external_cache/environment/NA2015.
Deploy the xdstools?.war in tomcat
Open the ui for the xdstools: http://[servername]:11080/xdstools
Click "Toolkit configuration"
Password: "easy"
Configure the tomcat server.xml to use these keys for mutual TLS support; see tomcat installation steps for details.
Set external cache:[tomcat-dir]/toolkit/external_cache (create the directories as well)
Set toolkit port to 11080.
Toolkit Host: ttpedgedev.sitenv.org
Default Env "NA2015"
Save; set the application.properties for ett to point to this and restart.

James server installation steps

Unzip james-server-app-3.0.0-beta5-20141114.003126-724-app.tar.gz in the (tar xvf james-server-app-3.0.0-beta5-20141114.003126-724-app.tar.gz) directory /opt - this command should create a directory /opt/james-server-app-3.0.0-beta5-SNAPSHOT under which James is unzipped - we will refer this directory as [james-dir].

tar zxv installs/james-server-app-3.0.0-beta5-20141114.003126-724-app.tar.gz

Java 8 installation may be required.

On a 64-bit system there is a bug that prevents the server from starting. Use this workaround.

cd [james-dir]/bin
mv wrapper-linux-x86-32  wrapper-linux-x86-32.bak
cp wrapper-linux-x86-64 wrapper-linux-x86-32

In conf directory, rename "smtpserver-template.xml" to "smtpserver.xml"

cp smtpserver-template.xml smtpserver.xml
cp imapserver-template.xml imapserver.xml
cp popserver-template.xml popserver.xml

Add <handler class="gov.nist.healthcare.ttt.jamesext.RequireTLSAuthCmdHander"/> to the block in the smtpserver.xml.

vi smtpserver.conf
(<handler class="gov.nist.healthcare.ttt.jamesext.RequireTLSAuthCmdHander"/> )
Also uncomment this line:  <authRequired>true</authRequired>
Comment this line:    <!--authorizedAddresses>127.0.0.0/8</authorizedAddresses-->
Upload file from Repository (ttt-jamesext-0.0.1.SNAPSHOT.jar)
Move ttt-jamesext-0.0.1.SNAPSHOT.jar to [james-dir]/conf/lib directory.

In log4j.properties file (in conf director), set "log4j.logger.james.smtpserver=DEBUG, SMTPSERVER" (DEBUG, not INFO) [james-dir]/conf ./james start (as root) (cd [james-dir]/bin)

For STARTTLS: Step 1: Upload the keystore file from the repository to [james-dir]/conf

Step 2: Set the startTLS to be true in the smtpserver section and add the keystore path

        Cd [james-dir]/conf
        Vi smtpserver.xml

Change these two lines (fill in the right password for the keystore):

        <tls socketTLS="false" startTLS="true">
        <secret>password-goes-here</secret>

also edit the imapserver.xml and pop3server.xml to edit starttls to ‘true” and set the password. Since we uploaded the keystore to the default place, path remains the same.

        Cd [james-dir]/conf
        
        Vi imapserver.xml
        <tls socketTLS="false" startTLS="true">
        Change password for keystore
<secret><password></secret>

[Optional step for preventing relay] mailetcontainer.xml: <mailet match="RecipientIsRegex=(?i)^((?!sitenv.gov).)*$" class="ToProcessor"> Do the same STARTTLS keystore for imapserver.xml and popserver.xml

Adding domain name and users:

cd [james-dir]/bin
james-cli.sh -h localhost -p 9999 adddomain domainname (ttpdsdev.sitenv.org in this case)
james-cli.sh -h localhost -p 9999 adduser user@domainname password  (password: smtptesting123)

(OR) Download and run adduser.sh file from the repository giving the domain name as the parameter.

Also: upload the fetch accounts with mail attachments. Create folders names “FOLDER’ and ’folder’ on the imaptesting account.

java -jar mailprotocols.jar gov.nist.healthcare.ttt.smtp.util.LoadInbox

Supply Hostname [example: smtp.gmail.com] UserName/Password {any account can be used as this is for sending mail] Path Name [use the folder structure from the repo - 2015-Certification-C-CDA-Test-Data-master.zip] Dest email: use the foldername@domainmane for each folder

[ett.jar will work as well as it contains mailprotocols.jar]

Point the TTPEdgeDev to TTPDSDEV james server: Go to ttpedgedev.sitenv.org/sites/ett and edit application.properties for these lines: ett.smtp.host = ttpdsdev.sitenv.org ett.starttls.address=[email protected] ett.other.address=[email protected] We are working on pointing the forgot password and other type of services which have been using the nist email server to one of our james. Please find the related entries and point to the james server:

direct.listener.email.host=ttpdsdev.sitenv.org
direct.listener.email.port=25
direct.listener.email.auth=true
[email protected]
direct.listener.email.password=<password here>
direct.listener.email.starttls=true
direct.listener.email.gmailStyle=false

To get cert file from keystore : (To make forgot password functionality work with self signed cert of James).

keytool -export -alias james -keystore keystore -rfc -file james.cert
keystore password : changeit

To import james cert to java cacerts: Make sure you are in dir which contains cacerts (For example /usr/lib/jvm/java-8-openjdk-amd64/jre/lib/security)

sudo keytool -keystore cacerts -importcert -alias james -file james.cert
keystore password : changeit

Direct RI server installation steps

The original document for the installation steps is here

However it is outlined again here (in a shorter version).

Install Java 8 (same steps as above): Note that the direct RI installation page recommends Java 7, we are moving to Java 8 for the whole installation. set JAVA_HOME to this path for the next steps.
Download Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 1.4.2 unzip jce_policy-1_4_2.zip For the below case the java home is : /usr/lib/jvm/java-8-openjdk-amd64
```
sudo cp jce/US_export_policy.jar $JAVA_HOME/jre/lib/security
sudo cp jce/local_policy.jar $JAVA_HOME/jre/lib/security
```

<TODO: ETT Direct requires a different strength file>

Add the domain according to the guide.
Configure the certificates for this domain.

There is an issue with the Direct RI derby column size when importing private key in the above step. The following workaround can be used:

Download db-derby-10.12.1.1-bin.tar.gz
Unzip using tar xzvf

Run ij (derby manager) after shutting down tomcat

cd $DIRECT_HOME/apache-tomcat-7.0.59/bin
sudo ./shutdown.sh
Cd /opt
$ sudo /opt/db-derby-10.12.1.1-bin/bin/ij
connect ‘jdbc:derby:$directhometomcat/bin/nhindconfig’;
alter table nhind.certificate alter column certificatedata set data type blob(16k);
disconnect;
exit;
Restart tomcat and now you should be able to import.
$ cd $DIRECT_HOME/apache-tomcat-7.0.59/bin
$ sudo ./startup.sh

Configure James as per the RI installation guide; add a user hisp-testing@domain.

Appendix A

Install Java 8 openjdk.

sudo add-apt-repository ppa:openjdk-r/ppa
sudo apt-get update
sudo apt-get install openjdk-8-jdk
sudo update-alternatives --config java
sudo update-alternatives --config javac
Make sure that java -version points to the installed Java 8 openjdk.

In case of package errors, you can try

sudo rm /var/lib/apt/lists/* -vf
sudo apt-get update

Appendix B - Tomcat 7 installation

sudo apt-get install tomcat7

Recommendation: Certain versions of tomcat seem to have issues, so please use tomcat-7.0.53 available here.

sudo tar zxvf /opt/installs/apache-tomcat-7.0.53.tar.gz

Also note that since the Name Server packaged with Direct comes with its own tomcat, it can be used for the toolkit and validator; however for load balancing purposes, the validator is installed in the James server.

XDS Toolkit requires additional configuration in the server.xml: <Connector port="11084" SSLEnabled="true" maxThreads="150" secure="true" protocol="HTTP/1.1" scheme="https" clientAuth="false" SSlProtocol="TLS" sslEnabledProtocols="TLSv1.2,TLSv1.1,TLSv1" SSLCipherSuite="-ALL:HIGH:!ADH:!SSLv3:!MD5:!RC4" SSLCertificateFile="/opt/tomcat7/toolkit/external_cache/environment/NA2015/cert.pem" SSLCertificateKeyFile="/opt/tomcat7/toolkit/external_cache/environment/NA2015/key.pem" keystoreFile="/opt/tomcat7/toolkit/external_cache/environment/NA2015/keystore" keystorePass="changeit" keyAlias="1" truststoreFile="/opt/tomcat7/toolkit/external_cache/environment/NA2015/keystore" truststorePass="changeit" />
MDHT Validator requires additional configuration.

Appendix C - MySQL installation

Install mysql

sudo apt-get install mysql-server [root password set to: <amimysqlroot>]]
sudo mysql_secure_installation
sudo mysql_install_db
sudo mysql -u root -p 
create database direct
create user 'direct'@'localhost' identified by ''
grant all on direct.*  to direct

Database schema can be found here. Saving this in a file createdb.sql, you can run this myqsql command:

mysql direct -u direct < createdb.sql

Appendix D - Name server

Follow the "Direct RI server steps" - since it comes with name services (the steps corresponding to James server need to be skipped, since ETT has a listener in the port 25).

Also, Apache installation is recommended for URL rewrite to make the ETT available through 443 using https. For proxy and ssl support additional steps maybe required.

   sudo apt-get install apache2
   sudo a2enmod proxy_http
   sudo a2enmod ssl

For ssl configuration the following steps maybe required:

copy the p12, key, cert files to /opt/ttp/certificates/private
create a pp.out in the same directory to echo the passphrase for bypassing sslpassphrasedialog on restart
add these two lines to ssl config

        SSLCertificateFile    /opt/ttp/certificates/private/star.crt
        SSLCertificateKeyFile /opt/ttp/certificates/private/star.key

If you have a passphrase you may want to add this to ports.conf under

   SSLPassPhraseDialog exec:/opt/ttp/certificates/private/pp.out

Add these lines in the site conf files:

    <VirtualHost *:80>
        DocumentRoot /var/www
        ServerName ttpedgedev.sitenv.org
        ProxyPreserveHost On
        SSLProxyEngine on
        TimeOut 10000
        ProxyTimeout 10000
        Redirect    301    /     https://ttpedgedev.sitenv.org/ttp/

and correspondingly in the ssl config:

       SSLProxyEngine on
        Redirect 301 / https://ttpedgedev.sitenv.org/ttp
        TimeOut 10000
        ProxyTimeout 10000
        ProxyPass       /ttp    https://ttpedgedev.sitenv.org:12080/ttp
        ProxyPassReverse        /ttp    https://ttpedgedev.sitenv.org:12080/ttp

Provide feedback

Saved searches

Use saved searches to filter your results more quickly