MESH client: advanced and other settings

This page describes more advanced configuration options for MESH client, as well as further information on elements of the installation process that are not included in the general MESH client installation guidance. This information links closely and in conjunction with the MESH client installation guide.

This information links closely and in conjunction with the MESH client installation guide.

Advanced configuration settings via editing the meshclient.cfg file

Below is a description of the settings which can be altered to fine tune the behaviour of the MESH client.

Within the <MESHConfig> tag
Setting	Description
PrimaryURL	The location of where the MESH client will connect. For example: <PrimaryURL>https://mesh-sync.national.ncrs.nhs.uk</PrimaryURL>
LogPath	The location where the mesh.log files will be created. For example: <LogPath>C:\MESH-APP-HOME\log</LogPath>
KeyStorePath	This location is for the MESH keystore file. For example: C:\MESH-APP-HOME\KEYSTORE\mesh.keystore
KeyStorePassword	This is the Keystore password supplied with the user account details. If the password used contains a ‘£’ sign, the meshclient.cfg file will need to be saved using UTF-8 encoding to enable the password to be used. The suggestion is that the password is limited to alphanumeric characters.
WorkPath	This location is used by the client to install internal files, such as lock files, to enable it to function properly. For example: <WorkPath>C:\MESH-APP-HOME\working</WorkPath>
ProxyPath	The path to the proxy.ini file. The existence of this path tells the client that proxy connectivity is required and the proxy.ini file will be read to determine the location and parameters associated with the proxy server. For example: <ProxyPath> C:\MESH-APP-HOME\proxy</ProxyPath>
SignalPath	The path to the signal file, mexclient.sig. For example: < SignalPath>C:\MESH-APP-HOME\sig</ SignalPath>
PollPeriod	PollPeriod is defined in minutes and is the period of time the client waits between sending and receiving messages to and from the MESH Service. The default poll period is 10 minutes. For example: <PollPeriod>30</PollPeriod>
ServerRetry	The number of retries allowed for a message if the MESH server is unavailable (but not busy). If not specified, the default is 3. For example: <ServerRetry>3</ServerRetry>
MaxMessages	The number of messages that can be uploaded/downloaded per poll. The minimum value is 20 and the maximum value is 10,000 with a default of 100. This will allow for controlled amounts of data to be transferred between client and server. The client will hold the connection and toggle between the upload and download tasks based on the value set until all messages have either been sent or collected. For example upload 100, download 100, upload 100, download 100 etc, until all activity is complete at which point the MESH client will close the connection to the central server and will not attempt to poll again until the time defined by PollPeriod has elapsed. For example: <MaxMessages>100</MaxMessages>
MaxMessagesUp	An individual MaxMessagesUp tag has been introduced to give the administrator more control over message flow to the MESH server. The value ranges from a minimum of 20 to a maximum of 10,000. If a value is specified outside of the range the default value of 100 will be used. Utilising the MaxMessagesUp tag will override both the default value of 100 and any MaxMessages value specified in the client configuration file. If there are still messages to be uploaded after the MaxMessages cycle has completed then the client will poll again until all messages have been sent. For example: <MaxMessagesUp>100</MaxMessagesUp>
MaxMessagesDown	Similar to MaxMessagesUp but for message downloads, overriding both the default value of 100 and any MaxMessages value specified in the client configuration file. For example: <MaxMessagesDown>200</MaxMessagesDown>
MaxConnections	This is the number of parallel processes that the MESH client can run. The default is 8 but if the number of CPU cores on the client hardware is lower than this, it will be equal to that number (if the value has been set higher). For example: <MaxConnections>4</MaxConnections>
AutoUpgrade	This setting defaults to N. If it is set to Y, the MESH client will check for updates to the client software every two days and will automatically download and install them. For example:. <AutoUpgrade>N</AutoUpgrade>
ProcessingDelay	This setting defaults to 5 seconds. It specifies how long a file needs to reside in the Out folder before the MESH client will attempt to process it. The time used is when the CTL file has been successfully written to disk. This avoids the potential issue where a CTL file is copied into the Out folder before the DAT file and the MESH client moves the CTL into the Failed folder as a malformed message. For example: <ProcessingDelay>5</ProcessingDelay>

Within the <Client> sections
Setting	Description
ClientIdentity	Site specific identity for the MESH client. Equivalent to the username. For example: <ClientIdentity>MAILBOX1</ClientIdentity>
ClientAuthentication	Site specific authentication token for the MESH client. <ClientAuthentication>ClntAuth1</ClientAuthentication>
InterfaceRoot	The path to the root of the MESH client File Interface. For example: <InterfaceRoot>C:\MESH\MESH-DATA-HOME\MAILBOX1</InterfaceRoot>
CollectReport	Parameter controlling the generation of reports by the MESH client, indicating that it has taken responsibility for an outbound message. Defaults to N For example: <CollectReport>N</CollectReport>
TransferReport	Parameter controlling the generation of reports indicating that the transfer of the messages to the MESH server has succeeded. Defaults to N. For example: <TransferReport>N</TransferReport>
PollReport	Parameter controlling the generation of reports indicating if the poll to the MESH server to check for received transfers has succeeded or failed. Defaults to N. For example: <PollReport>N</PollReport>
SaveSent	Parameter controlling the copying of sent messages into the SENT folder on successful transfer to the MESH service. Defaults to N. <SaveSent>N</SaveSent>

Create proxy connectivity

The MESH client allows you to connect to the service via a proxy server using “Basic Authentication” or “No Authentication” levels only.

To connect through a proxy server, create a proxy.ini file and place in the folder location specified by the </ProxyPath> tag in meshclient.cfg.

Proxy file format parameter	Description
useproxy	A flag to enable or disable proxy use (1 = ENABLE, 0 = DISABLE).
ipaddress	The TCP/IP address of the proxy server through which a connection to the MESH service is required.
port	The port on the proxy server used for the connection.
user	Username used in basic authentication by the proxy server. Ignored if “no authentication” is used on the proxy server.
password	Password used in basic authentication by the server. Ignored if “no authentication” is used on the proxy server.

To ensure proxy connection, the following three things need to be in place:

The proxy.ini file is saved in the exact same file location specified in the </ProxyPath> tag in the meshclient.cfg file.
The proxy file is made correctly.
The “useproxy” section of your proxy.ini file =1.

If ever you wish to disable the proxy connection, you can change the proxy.ini file to useproxy=0.The MESH client will assume that no proxy connection is required and will attempt to connect directly to the MESH service found at the </PrimaryURL> location.

Logging level configuration via editing the log4j.xml file

Upon start up, the MESH client will read the settings contained within the log4j.xml file to produce the required level of logging. Logging is a log of all actions performed by MESH, including start-up, sending data, receiving data, and any errors that may occur. The logs are helpful to look at if some of your files fail to send correctly.

Logging levels can be altered to be more or less detailed in their description of activities. You can change the logging levels in the <level value=”info”/> field by changing the “info” section. From least to most detailed, the options are: “error”, “warn”, “info”, “debug” and “trace”. For example, if you wished to have very detailed logs, your log4j.xml file will have the field of: <level value=”trace”/>.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE configuration SYSTEM "log4j.dtd">
<log4j:configuration xmlns@log4j="http://jakarta.apache.org/log4j/">
<appender class="org,apache.log4j.DailyRollingFileAppender" name="rollingappender">
<param name="File" value = "C:/MESH-APP-HOME/log/mesh.log"/>
<param name="DataPattern" value="'.'yyyy-MM-dd"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%d:[%-20t]:%-5p:%-20c{1}:%m%n"/>
</layout>
</appender>
<logger name="org.nhs.mesh">
<level value="info"/>
</logger>
<root>
<priority value="error"/>
<appender-ref ref="rollingappender"/>
</root>
</log4j:configuration>

Signal file

If the signal is valid, the MESH client response is to perform the requested action, log the event and update the signal file with NO ACTION.

Valid signals for MESH client
Signal Name	Value	Meaning
NO ACTION	0	No action required or previous action complete.
EXIT	1	Close client down at the next available opportunity.
RESUME	2	Re-enable the poll timer and commence processing messages.
PAUSE	3	Disable the poll timer until resume.
POLL NOW	4	Start polling mailbox(es) now rather than after expiry of the poll timer. If there is a pending priority mailbox, do this one first. Resume if paused.
LOAD CONFIG	5	Re-read the configuration file after processing the current mailbox.
DISABLE MBX n	6	Disable the given mailbox. The signal must have an accompanying ClientIdentification string included otherwise this will have no effect.
ENABLE MBX n	7	Enable the given mailbox if disabled. The signal must have an accompanying ClientIdentification string otherwise this will have no effect.
POLLMBX n	8	Poll the next specified mailbox (In multi-mailbox mode). This forced the client to poll a mailbox of choice. The signal must have an accompanying ClientIdentification string otherwise this will have no effect.
CHECK UPGRADE	9	Check if an upgrade to the MESH client is available and if so, download. The client will only install it if AutoUpgrade is set to Y.

Install MESH client on Linux Operating System

Installation of the MESH client on Linux servers follows exactly the same process as that detailed for a Windows install. The same java file installation file is used; mesh-6.2.0_20180601.jar.

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

# java –jar mesh-6.2.0_20180601.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.

Once the installation is complete and the configuration details have been input, the /MESH client can started.

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.

The MESH client can 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.

Upstart service (on Ubuntu 14.04)

Create a file in /etc/init/ called mesh.conf which will have the below format:

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

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.configurationFile=./log4j2.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

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

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.

Last edited: 6 October 2022 1:29 pm