installing

Installing Toolkit

Table of Contents

• Download
• System set up
• Install the WAR
• Create the External Cache
  • Optional: Add Files for Testing Imaging Functions
• Launch Toolkit
• Configure
• Auto-install of codes.xml and certificates
• Configuring Tomcat
• Configuring for TLS
  • Client TLS configuration
  • Server TLS configuration
• Upgrade Toolkit from Prior Version

Download

The downloads are found at https://github.com/usnistgov/iheos-toolkit2/releases. Grab the most recent.

System set up

Java version 8 and Tomcat version 7 or later. We run on Tomcat 9.

Version 4: Development environment was Oracle Java 8 and Tomcat 7.

Version 4: If you are testing SAML then Java 8 is required. See Issue with Java 7 and Toolkit 4 for details.

Version 7.7.0: Java 9 is supported.

Install the WAR

The above download is for the WAR file for toolkit. This should be installed in Tomcat by copying it to the webapps directory. Tomcat should open it immediately. If not then restart Tomcat.

If manual extraction of the WAR file contents is needed, do not use unzip to extract contents, as this likely corrupts some international language file names if there were used. Use jar -xf xdstools.war to extract contents manually if needed.

Multiple versions of toolkit can be run at the same time from the same instance of Tomcat. If you name the downloaded WAR file xdstools2.war then it will run from that name (http://host:port/xdstools2). Change the filename (before you move it to Tomcat’s webapps directory) and the URL will follow. Technically this name is the App Context.

If you run multiple copies they must each have their own private external cache.

Version 4: As of Version 4 the download will be named xdstools4.X.Y.war and should be renamed to xdstools4.war before installing it in Tomcat. Actually this is only our convention. It can be installed under any name you like. See Renaming Toolkit for details.

Create the External Cache

The External Cache is an area on local disk that Toolkit uses for saving generated data. This is a directory on the same machine as Toolkit. The path to this directory should not contain any spaces or special characters. Create this directory now. You will configure toolkit to use it in a later step.

Optional: Add Files for Testing Imaging Functions

If you are testing XDS-I.b or XCA-I.b, there is additional configuration required. You can find those instructions here: Configuring Toolkit for Imaging Tests. If you are only concerned with the traditional XDS.b, XCA, …​ tests, you can ignore this.

Launch Toolkit

If you just installed Tomcat for the first time and are running it on your desktop then the URL will be

http://localhost:8080/xdstools2

assuming the WAR file for toolkit was xdstools2.war when you moved it to Tomcat’s webapps directory.

Version 4 note: Version 4 is delivered as xdstools4.war so the URL will be

http://localhost:8080/xdstools4

When toolkit is opened it will complain about not finding the External Cache. That gets configured next.

Configure

When Toolkit starts for the first time it is likely that the configured External Cache location will not exist on your machine. The exact error message will vary since it is coming from your system. Either way the error will be displayed in a dialog box. Hit Ok to get rid of the error and continue below.

At the top of the window is a link labeled Toolkit Configuration. Open it. It will challenge you for a password. It is easy.

If the Toolkit Properties are not displayed and you get another error dialog box instead then there is a problem you need to report. See [[Reporting Toolkit Installation Problems]].

At a minimum you need to enter your local value for the path to the External Cache. If you type it wrong the Save button will verify so you will get feedback.

Note to Windows users - the path to your External Cache is probably something like c:\Toolkit. Here are variants that we have seen work on Window systems:

/c:/Toolkit
c\:\\Toolkit

If the External Cache directory is empty at this point, toolkit will initialize it.

Other things you may want to configure…​

If you are going to use simulators then you will need to enter a real hostname and port number where toolkit is running. These get configured into the endpoints for simulators.

If you are going to use a Registry simulator then you will need to allocate a few ports for Patient Identity Feed listener to use. These are listed as Listener Port Range. Each Registry simulator allocates a port so make sure to supply enough.

TLS configuration will be discussed separately. It is a little more involved.

Auto-install of codes.xml and certificates

As of Version 4 Toolkit is distributed with the most recent version of codes.xml and its certificate for Pre-Connectathon and Connectathon testing. These are kept in an environment named default. This environment will be automatically installed by Toolkit the first time it boots. It will not over-write an existing environment named default. If you already have an environment named default delete or rename it and restart Tomcat. The new default environment will be installed.

Note: the auto install of the certificate will only affect Toolkit as client. When using simualtors (Toolkit as server) it is also necessary to configure Tomcat.

Configuring Tomcat

Toolkit releases prior to v7.7.1 may have used a default port 9770. Check if non-TLS Tomcat Connector port is the same as Toolkit non-TLS port. If the XDS Toolkit you downloaded was configured with Toolkit Port 9770 and Tomcat non-TLS is configured for port 8080, update Toolkit Properties Toolkit Port to match Tomcat non-TLS port. In XDS Toolkit, click the Toolkit Configuration link on the left menu, change the Toolkit Port to 8080, and click Save. (Default admin password is easy.) Tomcat or the XDS Toolkit web application should be restarted for the change to take effect. Upon restart, existing simulator ports are automatically updated.

In Toolkit Release v7.7.1 and above, The default Toolkit non-TLS port 8080 matches the default Tomcat port 8080.

If you are not using TLS then Tomcat requires no configuration.

Configuring for TLS

Toolkit acts as a client, initiating connectations, and as a server, accepting connections. Client and server must be individually configured for TLS.

Client TLS configuration

Assuming you are using the default Environment, the Java Keystore is stored at

    ExternalCache/environment/default/keystore/keystore

with the keystore password saved in

    ExternalCache/environment/default/keystore/keystore.properties

When Toolkit automatically builds the default External Cache, the keystore for IHE Connectathon testing is installed. These certs are issued by the IHE Gazelle CA. If you need to install a different cert then do that in a different Environment.

Server TLS configuration

See Toolkit security background information here and TLS configuration here and for instructions.

Upgrade Toolkit from Prior Version

With no extra configuration, Toolkit maintains a properties file under the Tomcat folder structure in …​/WEB-INF/classes/toolkit.properties.

If you install a new version of Toolkit, it will write over your existing properties file. You will have to manually edit the properties or keep a copy of the file and drop it into the proper folder after Tomcat has expanded the new war file.

Starting with version 7.1.2 it is easier to manage the toolkit.properties file that contains configuration parameters. Toolkit now looks for a system property called TOOLKIT_PROPERTIES. If it finds this property, Toolkit uses the string in this property as the absolute path to your properties file. It does not point to a folder. It does point directly to a file. That means you do not have to use toolkit.properties as the filename. In the Tomcat structure, you can modify bin/catalina.sh (or bin/catalina.bat) by modifying JAVA_OPTS. For example:

JAVA_OPTS="$JAVA_OPTS $JSSE_OPTS -DTOOLKIT_PROPERTIES=/opt/xds/master-environment/properties/toolkit.properties

If you do not include the system property, Toolkit then looks for the file named /etc/toolkit/toolkit.properties. Yes, this is aimed at the Linux crowd. If it finds that file, Toolkit uses it as the properties file. Note that it is up to you to make sure that file is writable by Tomcat. This might help for you running Toolkit in Docker.

Finally, if Toolkit does not find the properties file using either of those methods, it returns to the standard behavior of using the file …​/WEB-INF/classes/toolkit.properties to hold those properties.