MESH Client Installation Guidance

MESH Client Installation Guidancev1.3 17/07/2018

Document filename: MESH Client Installation Guidance
Directorate / Programme / Operations and Assurance Services / Project / Spine Services/ MESH
Document Reference / <insert>
Project Manager / Andrew Meyer / Status
Owner / Clare Cooke / Version / 1.2
Author / Simon Richards / Version issue date / 28/07/2017

The Health and Social Care Information Centre is a non-departmental body created by statute, also known as NHS Digital.

MESH Client Installation Guidancev1.3 17/07/2018

Document Management

Revision History

Version / Date / Summary of Changes
0.1 / 24/04/2016 / Initial version.
0.2 / 27/04/2016 / Changes after initial review
0.3 / 28/04/2016 / Changes to recirculated document + additions
0.4 / 28/04/2016 / Additions for Linux install and service
1.0 / 29/04/2016 / Issued as version 1.0
1.1 / 15/03/2017 / Update for new client version
1.2 / 28/07/2017 / Review prior to release of revised Implementation pack
1.3 / 17/07/2018 / Review prior to release of revised Implementation pack

Reviewers

This document must be reviewed by the following people:

Reviewer name / Title / Responsibility / Date / Version
Stuart Baskerville / Spine2 Release Manager
Marta Raper / Spine2 Project Manager
Sarga Moore / MESH Service Manager
Kathryn Common / Senior Communications Officer
Tom Daley / Solution Assurance

Approved by

This document must be approved by the following people:

Name / Signature / Title / Date / Version
Ash Raines

Glossary of Terms

Term / Abbreviation / What it stands for
API / Application Programming Interface
DTS / Data Transfer Service
EPR / End Point Registration
HSCIC / Health and Social Care Information Centre
keystore / Repository for security certificates
MESH / Messaging Exchange for Social Care and Heath
MOLES / MESH Online Enquiry Service
RA / Registration Authority
RATS / Registration and Tracking Service
RBAC / Role-Based Access Control

Document Control:

The controlled copy of this document is maintained in the NHS Digital corporate network. Any copies of this document held outside of that area, in whatever format (e.g. paper, email attachment), are considered to have passed out of control and should be checked for currency and validity.

Contents

1Introduction

1.1Purpose of Document

1.2Background

2Pre Installation Checks

2.1Configuration and Network Access Check

2.2End-Point/Mailbox Registration

2.3Spine End-Point Certificates

2.4Installation Pre-requisites

3Windows Installation

3.1Overview

3.2Install Software on Windows

4Linux Installation

4.1Install Software on Linux

4.2Running the Client on Linux

5Installing a new MESH Client over an existing Installation

5.1Installation Approach

6Running the MESH Client as a Service

6.1MESH Client Windows Service Installation

6.2MESH Client Linux Service Installation

7Contact NHS Digital

8Appendix

8.1Example MESH Client Configuration File

8.2Example Auto-Install Script

The Health and Social Care Information Centre is a non-departmental body created by statute, also known as NHS Digital.

MESH Client Installation Guidancev1.3 17/07/2018

1Introduction

1.1Purpose of Document

The Messaging Exchange for Social Care and Health (MESH) Client Installation Guidance is intended for users who wish to use the MESH service.

MESH can support clinical and business processes requiring the transfer for data between NHS and their affiliated organisations.

This document is applicable tonew users of the service.

This document outlines the process for a new installation only and not the upgrade from an existing MESH client installation.

The intended audience for this document is MESH installers (responsible organisations) and end users.

1.2Background

NHS Digitalhas developed a new service to support the transfer of data between NHS and affiliated organisations. The Message Exchange for Social care and Health (MESH) is an in-house provided service. It has replaced the Data Transfer Service (DTS) which was provided under contract with BT. Theprovision of this new service has enabledNHS Digital to introduce a number of service improvements and deliver cost savings.

In January 2016 NHS Digital transitioned the DTS Central Service from BT to the NHS Digital MESH Service. In order to minimize any impact on end users NHS Digital provided a DTS Adapter to support the continued use of the DTS client software and connections to MESH. A migration from the DTS client software to the MESH client was completed in December 2016, at which point the DTS Adapter was decommissioned. All connections to MESH are now by MESH connection methods only, this means that the service is now operated and managed completely by NHS Digital.

The transition means the new service can adapt more easily to emerging user requirements in a more flexible and efficient manner.

2Pre Installation Checks

The MESH client is a Java based and allows systems to send and receive messages in the same way as the DTS client. The MESH client is more secure than the DTS client and is multi-threaded to improve performance particularly in multi-mailbox configurations.

Further information including supported platforms is included in the MESH client installation pack on the NHS Digital website.

2.1Configuration and Network Access Check

All MESH installations currently require a N3 connection. Internet facing services have been developed to support future uses of the service. Details of the local firewall configurations that must be in place to use the service are detailed in the Connecting to MESH Using DNS document on the NHS Digital website. Go to the guidance section for the latest version.

This document provides an overview of what configurations need to be implemented on client sites to ensure connectivity to MESH.

Details of the necessary URL and IP addresses for all elements of the service are provided within the document.

Installers are strongly advised to ensure that they have read this document and that the necessary configuration entries in are in place prior to installation of the MESH client.

The minimum requirement to access the MESH service to send and receive data is as follows;

DNS / Port / Protocol / External IPs / Target Application
mesh-sync.national.ncrs.nhs.uk / TCP/443 / HTTP over TLS / 155.231.48.156
155.231.48.220 / URL used by the MESH client to send and receive messages

2.2End-Point/Mailbox Registration

All newMESH client installations require an end-point / mailbox registration to be performed

Requests for new mailbox registrations can be submitted using the on-line form on the NHS Digital website.

When completing the New Mailbox Request Form all details must be provided including estimated message sizes and volumes so that a full impact assessment can be undertaken.

Failure to provide the required information may result in a delay in the registration process.

For correctly submitted New Mailbox Request Forms you should receive registration information within 10 working days as per the current SLA.

Once the registration is complete and approved the technical contact at the responsible organisation, as detailed on the request form, will be provided with the mailbox and authentication key details to support the local installation. Confirmation of the mailbox details excluding the authentication key will also be provided to the requestor.

2.3Spine End-Point Certificates

To improve security levels to meet the current Spine Core security requirements, all MESH clients and MESH Server API installations will require a specific local certificate.The new MESH client/MESH Server API rely on mutual authentication for higher security (both ends check that the other end has a valid certificate) as part of the log-on process.

If end sites already have a Spine End-Point Certificate in place to connect to Spine Messaging Interfaces, this can also be used for connection by the MESH client rather than applying for and deploying a new certificate.

For users that currently do not use a Spine End-Point Certificate, a MESH-specific certificate will be required. These are issued by NHS Digital’s Deployment Issue and Resolution (DIR) team. NHS Digital have produced a utility that will simplify the certificate request process. The utility that creates the certificate requestis Windows-based.

The certificate will need to be added to a Java Keystore (a repository of security certificates) so it can be used by the MESH client. This step is performed by the utility by supplying a password used to access the Keystore.If the Keystore does not exist, the utility will create it.

The detailed process for obtaining certificates is provided in a separate guidance document - the MESH Client Certificates Overview in the guidance section on the NHS Digital website, it is also included in the client installation pack...

2.4Installation Pre-requisites

The following pre-requisites need to be fulfilled before starting the MESH client installation.

A N3 connection or equivalent. (internet connection methods are available to support specific future use cases)
Mailbox and authentication credentials.
Spine End-Point Certificates have been generated and obtained.
The necessary firewall configurations are in place at end sites as detailed in the Connecting to MESH using DNS document.
The host environment must have a minimum software environment of Java Runtime Environment 1.7.
It is recommended that the host system has a minimum memory of 1Gb RAM to run the client in addition to operating system requirements.
Sufficient disk space for the client and the log files. It is recommended to allocate additional space on the server/PC hard drive for archive reports and sent/received folders.
Since the service provides access to patient identifiable data, it is recommended that the software is installed on a server or in a secured environment. Users can either authenticate directly onto the server or have shares established to the inbox and outbox folders.

3Windows Installation

3.1Overview

The following sections describe the installation method for installing the MESHclient on a Windows server. For installation of a new version of the MESH client over an existing client see section

It is assumed that the user performing the installation has logged onto the server with administration rights.

3.2Install Software on Windows

Step 1:

Download the latest installer package to a local drive.

Step 2:

Extract the zip file into a temporary directory and change to the extracted directory.

Ensure that the jar file is executable, right click on the file, select Properties and check the type of file shows as Executable Jar file.

Figure 1 - Confirm that the jar file is executable (windows)

Step 3:

Run the file by either double clicking on it or Right-click on the jar file and select Open With, then select the appropriate Java Runtime. Alternatively the jar file can be executed using the following command:

java –jar MESH-<version number>-installer-signed.jar

Step 4:

The following screen will be displayed:

Click the Next button

Figure 2 - Installation Step 1 of 10 (Windows)

Step 5:

You will be prompted to select the installation path. The installation process will suggest a path; this can be changed using the Browse button if required.

Note: Selecting the Quit button will stop the installation process.

Click the Next button.

Figure 3 - Installation Step 2 of 10 (Windows)

Note: If the target directory does not exist you will be warned that the installer will create it.

Figure 4 - Warning that directory will be created (Windows)

If the target directory does exist you will be warned that the installer may overwrite files in this directory. Confirm as required.

Click the Next button.

Step 6:

A default folder location for the install will be displayed. If you do not wish to install the client into this folder location you have the option to change the location.

Figure 5 - Installation Step 3 of 10 (Windows)

Once you are satisfied that the appropriate folder location is specified.

Click the Next button.

Step 7:

You will now be prompted to provide the details of the MESH Mailbox and the Mailbox Type. The mailbox details will have been provided as part of the New Mailbox Request form on the NHS Digital website. Ensure that the Mailbox Type is set to the default of MESH. For the installation of a CP-IS – Child Protection client an alternate installation process is available as additional detail is required.

Figure 6 - Installation Step 4 of 10 (Windows)

Click the Next button

Step 8:

A new feature of the MESH client is the Auto Update functionality. This feature ensures that

the MESH client being used is up-to-date by periodically checking with the MESH server whether there is a new version to install.

The MESH client will check every two days that the version running is the latest. If a newer

versionis available; it will automatically download the new version and install it. The update process will stop the client running and a restart locally would be required as the final part of the update process. Communications will be provided prior to the release of any new client so that end sites have the opportunity to review their configuration. It isrecommended that this setting is enabled, however if Suppliers/Responsible Organisations wish to manage the update process manually, this can be disabled.

Figure 7 - Installation Step 5 of 10 (Windows)

Step 9:

The installer will now summarise the installation tasks it will perform.

If you are happy with your installation then click the Next button.

Figure 8 - Installation Step 7 of 10 (Windows)

NB - there is no step 6 of 10 screen presented to the user in the case of a client with a Mailbox Type of MESH, step 6 of 10 is only applicable to a Mailbox Type of CP-IS, as in step 7 above. This is to support the requirement for input of additional information for CP-IS mailbox configurations.

Step 10:

The installer will now install the required packages, once it has completed the following screen will be displayed:

Figure 9 - Installation Step 8 of 10 (Windows)

Click the Next button

Step 11:

The Installer will now summarise its actions.

Figure 10 - Installation Step 9 of 10 (Windows)

Click the Next button

Step 12:

An option will then be provided to generate an automatic installation script so that similar changes can be undertaken for additional MESH installs. If you wish to use this option then select the button provided.

Figure 11 - Installation Step 10 of 10 (Windows)

An xml file will be generated, an example is provided in the appendix to this document; section 8.2. A default name for the script and folder location will be provided which can be updated as required. Make any changes as appropriate and save the file for later use. An option to cancel is also provided.

Figure 12 – Generate an automatic installation script (Windows)

If you do not wish to utilise this option to generate an installation script click Done to complete the installation.

Step 13:

The installation of the MESH client software is now complete. A few further configuration steps must be undertaken before the client is available for use.

The client software will have been installed in the following folder structure, unless changes to the folder locations have been made by the installer during the process.

Figure 13 – MESH Client Installed Folder Structure (Windows)

The configuration details for the client are held in the meshclient.cfg file. This file will need to be edited to input the mailbox and authentication key details for the specific client. These details should be available to the installer as detailed in section 2.4 Installation Pre-requisites.

Using a text editor such as Notepad ++ or Microsoft WordPad edit the configuration file and add the mailbox details and the authentication key. You will also need to add the password for the keystore that has been provided via separate process.

Enter the Mailbox name in <ClientIdentity>
Enter the Authentication key in <ClientAuthentication>
Enter the Keystore password into <KeyStorePassword>

Changes to configuration elements such as the log file locations and the logging level can also be made at this time.

The logging level is held in the log4j.xml file and can be edited in the same way as the meshclient.cfg file. The logging levels that the client can be set to are detailed in the Technical Specification document Section 4.9 Log Level Settings.

An example meshclient.cfg file is provided in the appendix of this document, section 8.1 and in the software download set.

Step 14:

Once all the configuration changes have been saved the client can be started by double clicking the runMeshClient.bat. If the client is running you will see the log file generated in the folder defined in the meshclient.cfg file. The default folder location for the log file is \MESH-APP-HOME\log for a new MESH installation.

NB: an uninstall option is provided and is located in \MESH-APP-HOME\Unistaller

4Linux Installation

4.1Install Software on Linux

Installation of the MESH client on Linux servers follows exactly the same process as that detailed for a Windows install in section 4 of this document. The same java file installation file is used;mesh-6.1.1_20170111-installer-signed.jar.

To run the install start a terminal session and enter the following command;

# java –jar mesh-6.1.1_20170111-installer-signed.jar

Follow the same detailed steps as documented for the Windows install.

As with the Windows client you will need to ensure that the Keystore has been populated, that the desired log level has been set and that meshclient.cfg contains the correct file paths and login credentials for your mailbox.