MESH Client Installation Guidance v1.2

Document filename: MESH Client Installation Guidance
Directorate / Programme Operations and Project Spine Services/

Assurance MESH
Services
Document Reference <insert>

Project Manager Andrew Meyer Status
Owner Clare Cooke Version 1.2
Author Simon Richards Version issue date 28/07/2017
MESH Client Installation

Guidance
Copyright ©2017 NHS Digital

MESH Client Installation Guidance v1.2 28/07/2017
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
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
Copyright ©2017 Health and Social Care Information Centre Page 2 of 25
The Health and Social Care Information Centre is a non-departmental body created by statute, also known as NHS Digital.
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
1 Introduction 5
1.1 Purpose of Document 5
1.2 Background 5
2 Pre Installation Checks 6

2.1 Configuration and Network Access Check 6
2.2 End-Point/Mailbox Registration 6
2.3 Spine End-Point Certificates 7
2.4 Installation Pre-requisites 7
3 Windows Installation 8
3.1 Overview 8
3.2 Install Software on Windows 8
4 Linux Installation 17
4.1 Install Software on Linux 17
4.2 Running the Client on Linux 17
5 Installing a new MESH Client over an existing Installation 17

5.1 Installation Approach 17
6 Running the MESH Client as a Service 18

6.1 MESH Client Windows Service Installation 18
6.2 MESH Client Linux Service Installation 21
7 Contact NHS Digital 23

8 Appendix 24
8.1 Example MESH Client Configuration File 24
8.2 Example Auto-Install Script 25
1 Introduction
1.1 Purpose 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 to new 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.2 Background
NHS Digital has 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. The provision of this new service has enabled NHS 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.
2 Pre 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.1 Configuration 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 URL used by the MESH client to send
155.231.48.220 and receive messages
2.2 End-Point/Mailbox Registration

All new MESH 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.3 Spine 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 request is 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.4 Installation 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.
3 Windows Installation
3.1 Overview
The following sections describe the installation method for installing the MESH client 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.2 Install 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.
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.
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.
Once you are satisfied that the appropriate folder location is specified.
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.

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
version is 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 is recommended that
this setting is enabled, however if Suppliers/Responsible Organisations wish to manage the
update process manually, this can be disabled.
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.
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:
Step 11:
The Installer will now summarise its actions.

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.
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
4 Linux Installation
4.1 Install 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.
4.2 Running the Client on Linux

Once the installation is complete and the configuration details have been input the MESH
client can started as follows;
• To run the Mesh client, type # ./runMeshClient.sh &
• To check that the Mesh client is running, type # jobs or # ps –ef | grep mesh
If the server is rebooted, the MESH client will need to be re-started again.
5 Installing a new MESH Client over an existing

Installation
5.1 Installation Approach
New versions of the MESH client will be released periodically as the service matures and
new functionality is introduced in support of requirements for extended use of the service.
NHS Digital will support the current and one previous version of the client. The latest version
of the MESH client is 6.1.1_20170111, the previous version is 6.0.1_20160413
The end user has a number of options in how they may deploy a new version of the client. It
is strongly advised that a backup of the existing client install should be done prior to
undertaking any client upgrade.
5.1.1 Install as if a fresh install
Undertake a completely fresh install as if no previous installation exists. The existing client
and/or the associated service, if used, must be stopped. Install the new client as detailed in
section 3 for MS Windows or section 4 for Linux, depending on the operating system of the
machine on which the new client will be deployed.
Once the installation process is complete the configuration and keystore can be copied from
the original installation and any additional configuration changes to take advantage of any
new functionality can be made. It is not necessary to apply for a new security certificate. The
configuration for the client is contained in the meshclient.cfg file within the \MESH-APP-
HOME folder. The keystore is stored in \MESH-APP-HOME\Keystore.
Once the configuration file and keystore have been copied to the new installation the client
and/or service should be restarted. The old client files should be removed or archived once
the new client deployment has been assured and fully operational.
5.1.2 Install over existing installation
The installation pack on the website along with the installation wizard and technical
documentation includes the latest MESH client file (meshClient-6.1.1_20170111.jar).
This file can be introduced into an existing installation of MESH as a replacement for the
meshclient.jar file.
Step 1: Download the installation pack from the website and unzip the contents.
Step 2: logon to the machine where the client installation resides
Step 3: Stop the MESH client and/or service
Step 4: goto the \MESH-APP-HOME\ folder and rename the meshclient.jar meshclient.old
Step 5: copy the meshClient-6.1.1_20170111.jar file from the installation pack to \MESH-
APP-HOME\
Step 6: rename the copied meshClient-6.1.1_20170111.jar file meshclient.jar
Step 7: Restart the MESH client and or service
Step 8: review the log file to see that the new client is running as expected.
If changes are required to be made to the client configuration they can be made at this time.
The client and or the service will need to be stopped. The attributes held in the \MESH-APP-
HOME\meshclient.cfg file and be changed, the service will then need to be restarted.
6 Running the MESH Client as a Service

6.1 MESH Client Windows Service Installation
The installation of the MESH client Windows Service should be completed after the MESH
client has been installed and tested.
The contents of meshclient_windows_service.zip MUST be extracted into the MESH client
Installation folder as chosen in step 2 of the MESH Client IzPack Installation. If the default
path was selected, this will be C:\MESH-APP-HOME.
6.1.1 Unpacking
Right-click on meshclient_windows_service.zip and choose to Extract All. Click Browse to
select the installation path of the DTS client and the files indicated below will be installed into
that location.
Figure 14. The MESH client install folder after extracting meshclient_windows_service.zip.
6.1.2 Amending the Batch Files

Before installing, check that the meshclient_service_install.bat and
meshclient_service_uninstall.bat files reflect the architecture of the Windows machine that
the MESH client is running on.
Open up a command prompt and enter: set | findstr ARCH
The output will indicate the type of architecture.
Figure 15. Finding the architecture of your Windows machine
Right-click on meshclient_service_install.bat and select Edit.

If the line @set ARCH=amd64 is different to your machine’s architecture, change it (to x86
or ia64) and then File, Save and Exit.
Repeat for the meshclient_service_uninstall.bat file.
Prior to the actual install, stop the MESH client (for example, by sending a “1” to the
mexclient.sig signal file) as the service cannot be started if it is already running.
6.1.3 Installing
Double-click on mesh_service_install.bat to commence the service installation.
Depending on security settings, you may be prompted with "are you sure?" type questions.
Select the appropriate response if you wish to install.
After the "Press Any Key to continue..." the service is installed (but not started).
Hit the Windows key, go to Run and open services.msc
Highlight the MESH client Service and click Start
For convenience, a SysTray icon is provided. To install it, double-click
mesh_service_systray.bat
Once installed, you can Right-click on the icon and start/stop the service, or double-click to
access further settings.
Figure 16. Systray icon double-click (for properties) or right-click (for basic menu)
6.1.4 Uninstalling
To uninstall the service, first ensure that it has stopped.
Double-click on mesh_service_uninstall.bat and this will remove the service but leave behind
the extracted files and folders for ease of re-creation should this be a required later.
6.2 MESH Client Linux Service Installation

The MESH client can be set up also be set up to run as a Linux service. As a Linux service if
the server is rebooted, the client will shut down safely and automatically restart once the
server is up. If the client has been started from the command line it would have to be
manually restarted every time the server is rebooted.
The way services are handled on Linux depends upon the “flavour” of the Linux distribution
and version. Some versions use upstart and some use systemd. For example, Ubuntu
14.04 uses upstart but has moved to systemd for version 15.04.
Below are examples of how the MESH client can be run as a service, using upstart and
system; choose whichever is compatible with your system.
6.2.1 Upstart Service (on Ubuntu 14.04)

Create a file in /etc/init/ called mesh.conf
description "Service for the MESH Client"
author "HSCIC"
start on runlevel [2345]

stop on runlevel [016]
chdir /MESH-APP-HOME
script
./runMeshClient2.sh
end script
pre-stop script
echo 1 > ./sig/mexclient.sig
sleep 5
end script
Figure 17. Upstart Service mesh.conf
To run the MESH client as a service, first ensure that it is not running.
# service mesh start
To check the status,

# service mesh status
To stop the service,

# service mesh stop
The script needs to execute runMeshClient.sh but it was found that subtle changes needed
to be made to the syntax to get it to work! A second version called runMeshClient2.sh was
created.
#!/bin/sh
RESTART=true
while [ "${RESTART}" = "true" ]; do
RESTART=false
java -Dlog4j.configuration=file:./log4j.xml -jar meshClient.jar ./meshclient.cfg

OUTCOME=$?
# If we get an exit code of 2 from the MESH Client, that means a restart is required.
if [ "${OUTCOME}" = "2" ]; then
# Apply any upgrades that have been downloaded
mv ./upgrades/meshClient-*.jar ./meshClient.jar
RESTART=true
fi
done
Figure 18. Upstart Service runMeshClient2.sh
6.2.2 Systemd Service (on CentOS 7)

Create a file in /etc/systemd/system called mesh.service
[Unit]
Description=MESH Client Service
[Service]
WorkingDirectory=/MESH-APP-HOME
ExecStart=/bin/sh ./runMeshClient2.sh
ExecStop=/bin/sh -ec 'echo 1 > ./sig/mexclient.sig'
ExecStop=/bin/sleep 5
[Install]
WantedBy=multi-user.target
Figure 19. Systemd Service mesh.service
Enable the service

# systemctl enable mesh
Start the service

# systemctl start mesh (…service mesh start works too!)
As with the upstart service, to get this to work changes need to be made to the original
runMeshClient.sh script the recommendation is to use the same runMeshClient2.sh used in
defining the service using Upstart.
7 Contact NHS Digital

For further information a dedicated MESH section has been created on the NHS Digital
website at: NHS Digital MESH Website
If users have specific question related to MESH please contact the National Service Desk.
8 Appendix
8.1 Example MESH Client Configuration File
8.2 Example Auto-Install Script

MESH Client Installation Guidance v1.2

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

MESH Client Installation Guidance v1.2

Hochgeladen von

Copyright:

Verfügbare Formate

Document filename: MESH Client Installation Guidance

Directorate / Programme Operations and Project Spine Services/

Document Reference <insert>

Author Simon Richards Version issue date 28/07/2017

MESH Client Installation

Copyright ©2017 NHS Digital

MOLES MESH Online Enquiry Service

Copyright ©2017 Health and Social Care Information Centre Page 3 of 25

2 Pre Installation Checks 6

5 Installing a new MESH Client over an existing Installation 17

6 Running the MESH Client as a Service 18

7 Contact NHS Digital 23

Copyright ©2017 Health and Social Care Information Centre Page 4 of 25

Copyright ©2017 Health and Social Care Information Centre Page 5 of 25

2 Pre Installation Checks

2.1 Configuration and Network Access Check

2.2 End-Point/Mailbox Registration

Copyright ©2017 Health and Social Care Information Centre Page 6 of 25

2.3 Spine End-Point Certificates

2.4 Installation Pre-requisites

Copyright ©2017 Health and Social Care Information Centre Page 7 of 25

3.2 Install Software on Windows

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

Figure 2 - Installation Step 1 of 10 (Windows)

Copyright ©2017 Health and Social Care Information Centre Page 9 of 25

Figure 3 - Installation Step 2 of 10 (Windows)

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

Copyright ©2017 Health and Social Care Information Centre Page 10 of 25

Figure 5 - Installation Step 3 of 10 (Windows)

Figure 6 - Installation Step 4 of 10 (Windows)

Click the Next button

Figure 7 - Installation Step 5 of 10 (Windows)

Copyright ©2017 Health and Social Care Information Centre Page 12 of 25

Figure 8 - Installation Step 7 of 10 (Windows)

Figure 9 - Installation Step 8 of 10 (Windows)

Click the Next button

Copyright ©2017 Health and Social Care Information Centre Page 13 of 25

The Installer will now summarise its actions.

Figure 10 - Installation Step 9 of 10 (Windows)

Click the Next button

Figure 11 - Installation Step 10 of 10 (Windows)

Copyright ©2017 Health and Social Care Information Centre Page 14 of 25

Figure 12 – Generate an automatic installation script (Windows)

Figure 13 – MESH Client Installed Folder Structure (Windows)

• Enter the Mailbox name in <ClientIdentity>

Copyright ©2017 Health and Social Care Information Centre Page 16 of 25

4.2 Running the Client on Linux

• To run the Mesh client, type # ./runMeshClient.sh &

5 Installing a new MESH Client over an existing

6 Running the MESH Client as a Service

Copyright ©2017 Health and Social Care Information Centre Page 18 of 25

6.1.2 Amending the Batch Files

Copyright ©2017 Health and Social Care Information Centre Page 19 of 25

Figure 15. Finding the architecture of your Windows machine

Right-click on meshclient_service_install.bat and select Edit.

Copyright ©2017 Health and Social Care Information Centre Page 20 of 25

6.2 MESH Client Linux Service Installation

6.2.1 Upstart Service (on Ubuntu 14.04)

description "Service for the MESH Client"

Copyright ©2017 Health and Social Care Information Centre Page 21 of 25

start on runlevel [2345]

To check the status,

To stop the service,

java -Dlog4j.configuration=file:./log4j.xml -jar meshClient.jar ./meshclient.cfg