23.03. mSupply client / server installation part 3

These steps need to be carried out after completing the steps described in:
20.01 mSupply client/server installation part 1
20.02 mSupply client/server installation part 2

If you are upgrading from a previous version...

If you are upgrading from a previous version of mSupply, first perform a data backup:

  • With mSupply server open as an application click on File> Backup…. This will generate a backup file of your current data with file extension .4bk.
  • Copy this file to at least one safe place, e.g. USB drive, a cloud service such as Dropbox.
  • Continue only when the .4bk file has completed transfer to the remote location.

Moving from pre v3.50?

There was a major upgrade of mSupply's internal structure in v3.50. If you are upgrading from a pre v3.50 installation of mSupply, Sustainable Solutions will need to convert your data so that it can be read by mSupply versions after v3.50. This conversion process is provided free of charge.

Obtain and run the mSupply Server installer

The client/server version of mSupply has two installers:

  • One installer, with the word Server in the title, is used to install the mSupply Server software on a single server computer.
  • The other installer, with the word Client in the title, is used to install the mSupply Client software on as many computers as you wish including on the server computer. You will be limited in how many clients can connect at any one time by the server licence you have purchased.

You must be logged on as Administrator to install mSupply Server with the correct permissions. Please consult your IT support staff if you require assistance to achieve this.

Once you have obtained the mSupply Server installer file, double click it to install. Here is what the mSupply server installation window should look like:

  • You may be asked by the OS whether 'you want to allow this app to make changes to your device?'. Click Yes
  • At the mSupply Server Setup Welcome screen, click Next
  • To proceed with the installation, you will need to click on the 'I agree to the terms of this license agreement' radio button and click Next
  • Unless you have good reason to do otherwise, don't change the installation folder, and click Next
  • Unless you have good reason to do otherwise, don't change the Shortcut folder, and click Next
  • At the Ready to Install window, click Next
  • After some time (minutes!) you will be shown the Installation Successful window. Click Finish

What is installed where:

We strongly recommend you do not change the default installation directories, which are as follows:

  • mSupply Server: C:\Program files\mSupply\mSupply Server
  • mSupply Client (see Installing mSupply Client below): C:\mSupply Client
mSupply Server installer also installs the following files and folders:

Starting the Server for the first time

There is no point in carrying out the following steps unless:

  • You are ready to create a new mSupply data file, or you have one to load.

Run mSupply Server

We need to run mSupply Server as an application until all configuration is completed. Don't run as a Service now as some configuration functionality is not enabled when run as Service.

Sometime it has been useful to allow the mSupply.exe to run as Administrator by default. This gives the application the right to modify data in folders that may have been unknowingly restricted by operating system.

View the mSupply.exe file inside the mSupply installation folder. View properties then Compatibility tab and set the file to always Run this program as an administrator. View the image below for better guidance.

We need to run the mSupply Server software as Administrator.

Find the mSupply Server executable (C:\Program files\mSupply\mSupply Server\mSupply.exe), right-click on it and select Run as administrator

You will then be presented with the following dialogue box:

Click Create to create a new data file or Open to choose an existing data file. The below image shows an existing data file.

Since Windows version 1803 and following, there can be issues with permissions to access folders located in individual user folders such as under My Documents. Therefore, it is now highly recommended to save your data file in the folder: C:\ServerName_mSupply_data replacing ServerName with the mSupply server (site) name, eg. C:\Hagen_AMS_mSupply_data.

You may get a question from the Windows Firewall requesting permission for mSupply to communicate through the Firewall.

Allow mSupply to communicate on both private and public networks.

If the above steps have succeeded, you should see the 4D Server Administration window:

Configure backups

  • Select Maintenance and then, under the 'band' titled Last backup select Preferences.
    • Scheduler: Set Automatic Backup: to Every day, at 20:00 or later, as long as it is a time when work is likely to be finished. It will have to be set earlier, say 16:00 if the server is switched off of an evening.
    • Configuration:
      • Content:
        • tick Data File
        • untick Structure File
        • untick User Structure File
        • Delete all 'Attachments' except the .4DIndx file:
        • If this server uses the Dashboard, then add the dashboard configuration files (normally C:\Progran Files\mSupply Dashboard\data\grafana.db and C:\Program Files\mSupply Dashboard\conf\custom.ini) to the backup - see figure below
        • Add the 4D Index (.4DIndx) and journal (journal) files to the backup. They should be in the same folder as the database. - see figure below
  • Backup File Destination Folder
    • If on physical hardware, this should be a separate physical disk (e.g. D:\mSupply_backups).
    • If on a virtual machine, it is meaningless to have a separate physical disk, and it should be C:\Users\Administrator\Documents\mSupply backups.
  • Log Management: Set .journal to the same parent folder as the backups.
    • If on physical hardware, this should be a separate physical disk (e.g. D:\mSupply_journal).
    • If on a virtual machine, it is meaningless to have a separate physical disk, and it should be C:\Users\Administrator\Documents\mSupply journal. *

If a location of the log file is already specified, and you want to change it, you need to untick the “Use Log” tick-box and then when you re-tick it you will be prompted for a new location.

  • Backup & Restore
    • General settings
      • tick Keep only last 15 backup files.
      • tick Backup only if the data file has been modified
      • Delete oldest backup file after backup
      • If backup fails: select Retry after 30 Seconds
      • tick Cancel the operation after 5 attempts.
    • Archive
      • Segment Size (Mb): None
      • Compression Rate: Compact
      • Interlacing Rate: None
      • Redundancy Rate: None
  • Automatic Restore
    • tick Restore last backup if database is damaged
    • tick Integrate last log if database is incomplete
  • Click OK

You will see the following dialogue box:

  • Click OK to create the first backup.

Configure cache

Edit > Database Settings > User settings for Data file

User Settings

Select Database and then set up the cache memory.

  • Tick Calculation of adaptive cache
  • Memory to be reserved for other applications and for the system: = 512 MB (default?)
  • Percentage of the available memory used for cache = 100%. According to the 4D v16.5 Database/Memory page, 'Percentage of the available memory used for the cache = 100% since there is only one 4D Server application.' If other applications running on the server need additional RAM, it should be added to the figure above.
  • Minimum size = 1,000 MB (default?)
  • Maximum size = can be set to any number, including greater than available RAM. If this number is greater than the available RAM, 4D will adapt the size of the cache according to the actual available RAM.
  • Flush Data Buffers every: 10 Minutes


  • Click OK
  • Exit 4D Server Administration window.
  • Check that the settings.4DSettings file has been created in the <DataFolder>/Preferences folder

If you haven't already done so, configure Interactive Services Detection.

The server should now be set to start automatically when the machine is turned on. This can be accomplished by setting the server to run as a service. Choose File > Register Current Database as Service.

If the Register Current Database as Service option is greyed out, you are probably not running the mSupply Server as Administrator. You need to quit the server and run as Administrator.

Once you have registered the Current Database as Service, Quit the 4D by clicking the close box on the top right (or choose File > Quit from the menus). You will then be shown a disconnect window something like this:

Type 0 into the box, and click OK . The server will quit.

Pin Services to the taskbar

It is important to be able to quickly observe the status of the 4D / mSupply Service. Therefore, we pin Services to the taskbar:

  • Click Windows icon
  • Type Services
  • Right-click the Services Desktop App
  • Select Pin to taskbar

Configure mSupply Service settings

Click on Services in the task bar. You will be shown a window like this.

Double-click on 4DServer: mSupply - fortunately it is usually the first item in the list!

You will be shown the 4DServer: mSupply service properties window. Change the Startup type in the drop-down list to automatic (Delayed start).

Log on as Local System account

Historically, on the Log On tab, the settings should be as shown immediately below. However, mSupply 3.85+ on Windows Server 2012+ and Windows 10 1803+ the service has had to assigned to “Log On” to an administrator account for mSupply service to start - see further below.

  • Make sure “Log on as” is set to “local system account” (or LSA for short)
  • Make sure “Allow service to interact with desktop” is checked.
  • Click OK to return to the list of services.
  • Close the Services window
Log on as administrator account

With mSupply 3.85+ on Windows Server 2012+ and Windows 10 1803+ the service has had to be assigned to “Log On” to an administrator account for mSupply service to start:

Help the mSupply Server Service find the data file

If you have configured the mSupply service to Log on as an administrator account, the following settings are likely not required.

Depending on the Windows version, the Local System Account may not have permissions to access the mSupply data file if it is not in the default location (in the Admin user's Documents folder). To fix this, the following steps are required:

  1. Download PSTools to the server
  2. Extract to C:\PSTools
  3. Run the Command Prompt As Administrator
  4. At the prompt, type cd C:\PSTools <Enter>
  5. Type psexec -i -s cmd.exe <Enter>
  6. The PsExec License Agreement dialogue box may open. Click AgreePsExec License Agreement
  7. A new Command Prompt window should open. In this new window, type whoami <Enter> You should see the following: nt authority\system If you don't, something has gone wrong and you need to close all Command Prompt windows and start again.
  8. Type cd c:\Program Files\mSupply\mSupply Server <Enter>
  9. Type mSupply.exe <Enter> The mSupply Server will open, prompting for the data file location:
  10. Click OK. The Select a 4D Data File window will come up, immediately followed by the Location is not available error message:
  11. Click OK on the error message window, and then select the correct datafile. The mSupply.4DC - 4D Server Administration window should open.
  12. <Ctrl>-Q to exit mSupply Server. Enter 0 for the time delay.
  13. Close both Command Prompt windows

From now on the 4D server should start automatically when the machine is turned on. There is no need to log-on to the machine.

Manually starting the mSupply Server Service

  • To manually start the mSupply Server Service, double-click the “Services” shortcut you made on the desktop, highlight the 4D server service, and click the triangular “start” button (looks like a “Play” button on a media player)

If clicking the Start Service button results in the Error 1: Incorrect Function, a registry edit (regedit) is necessary. Please only do this if you are confident and familiar with editing the registry. mSupply Support can help with this. Edit registry value:

  Path: SYSTEM\CurrentControlSet\Control\Windows
  DWORD: NoInteractiveServices

Change value 1 to 0

Once finished editing the registry, close regedit and return to the list of services and start the ISD service. It should now start!


Check that mSupply server is running correctly in Session 0:

  1. If you don't see mSupply server on Session 0 - Get back to Services and check 4D server properties:
    • LogOn should be set as “Local System account”
    • Enabled option “Allow service to interact with Desktop”
  2. Check if any Error window is showing up and need a OK confirmation to continue.
  3. Check if the datafile needs to be selected because it has changed folder.
Since 4D v17

Since v17 of 4D (the database engine underlying mSupply), when running mSupply as a Service, logging on as the Local System Account (LSA, as described below), mSupply MAY no longer have sufficient permissions to access the folder: C:\Program Files\mSupply\mSupply Server\Server Database\Preferences\Backup

If this is the case, it will result in the following error (which can only be seen in Session0):

If this happens, it needs to be fixed. The Solution is to edit permission of Users to allow Full control/Modify/Write to the Backup.XML file as shown here:

Manually stopping the mSupply Server Service

  • To manually stop the mSupply Server Service, first make sure clients are not connected, then double-click the “Services” shortcut you made on the desktop, highlight the 4D Server service, and click the square “stop” button (looks like a “Stop” button on a media player)

Manually starting the Service

Despite being configured so, the mSupply Service sometimes will not start when the server hardware starts. The service can be started through the Services:

From this point there should be no need to revisit any of the above procedures to operate mSupply. However, if you are testing, or starting a data file for a second organisation, you may wish either to change the data file mSupply is using or to create a new file.

The mSupply program (the files named “mSupply.4DC” and “mSupply.RSR”) store the path to the last data file used, and the next time mSupply is started, the previous data file that was open is opened again unless there is user intervention or the “old” data file has been moved to a new location.

To intervene, hold down the “alt” key as the 4D server starts up.

You will be shown the standard open/save window:

To create a new data file, click the “New” button.

To select an existing data file, navigate to the file's location then click the “Open” button.

Needed: mSupply Client software of the same version (or relatively recent) as the mSupply Server.

  • The mSupply server should run as a service on the server computer - see above. If any user needs to use mSupply on the server (not recommended, but possible, and sometimes necessary) then they should not be running the mSupply Server software. They should run the mSupply Client software, which should be made available to all user accounts.

OS date settings

Generally, mSupply will interact correctly with the local OS in terms of date format. However, as OS versions continue to evolve and handle dates differently, sometimes this does not work. We have found that very occasionally, if the OS date format is set to DD-MMM-YY (e.g. 20 APR 2020) then mSupply will not always handle the date well. It is recommended to set the system date to DD-MM-YY.

Obtain and run mSupply Client installer

You must be logged on as Administrator to install mSupply Client with the correct permissions. Please consult your IT support staff if you require assistance to achieve this.

  • Once you have obtained the mSupply Client installer file, double click it to install.

The mSupply client will be installed in the folder C:\mSupply\mSupply client on your computer.

mSupply client installer also installs the following files and folders:

  • A shortcut on the Desktop called mSupply client.
  • A folder called “\4D\Network” in the Windows folder on the startup volume, which contains network component files that need to be present for 4D to communicate over a TCP (and other types of) network(s).
  • No reports are installed on 4D client. Each time 4D client connects to the Server, reports that have been added or modified on the server are automatically copied to the client.
  • Installers have been set up to overwrite existing files, so reinstalling the software will restore any potentially corrupted files to their original state. The installer will not overwrite your data files, unless you have been unwise enough to name your data file “example data” and put it in the “example data” folder ;-).

For convenience, pin the mSupply client desktop shortcut to the taskbar.

If any other Windows users will use this computer to access mSupply, it is worth copying the mSupply client desktop shortcut to the C:\Users\Public\Desktop folder. This will place the shortcut on the desktop of each user. Each user will need to pin this shortcut from their desktop to the taskbar.

The C:\Users\Public\Desktop folder is normally a hidden folder. You will likely need to make it visible).

Additionally, if this computer is primarily used for running mSupply, then it is worth copying the mSupply client desktop shortcut to the Startup folder. The actual folder name changes with Windows version :-( so here are instructions: How to Add Programs, Files, and Folders to System Startup in Windows.

Starting the mSupply Client

Once the installation is completed, double-click the “start mSupply Client” shortcut on your desktop. A window something like this should appear:

The window lists available mSupply servers on your network (there should be only one!) Click on the server you wish to connect to.

  • Once you have connected successfully, the mSupply Client 'remembers' which Server you last connected to and stores this in the Recent tab. Whenever you run the mSupply Client, it will automatically connect to that server.
  • If, mSupply Client cannot connect to the mSupply Server, this window will pop up showing the Recent tab. You can try choosing the server there.
  • If, for some reason, network settings have been changed and you cannot connect from the Recent tab, remember to look at the TCP/IP tab as well.

Clicking the “OK” button will take you to the mSupply password entry window. For new data files, the password is user1 for the first user in the list. Click on the first user, then enter the password and click OK

mSupply Client software cannot see the mSupply Server?

Server is not visible?

  • To make it easy for you to connect, mSupply Server publishes details about available servers on a specific port. It is quite possible that products such as “Zone Alarm” and “Norton Personal Firewall” will block access to this port and stop discovery of the servers. Contact your system administrator if the list of available servers is blank.
  • Of course, it may be possible that the mSupply Server service is not running. Check Services to establish that.
  • Lastly, the Windows firewall may be blocking the Server publishing it's presence - see below.

Configuring Windows firewall on server

The Windows firewall may need to be adjusted to allow the Client to receive Server identification.

From the 4D tech email list:

  • When you launch 4D client, it broadcasts a udp message on the subnet, requesting all 4D servers to identify themselves.
  • The UDP message is sent from a random port to a destination port = 19813 (default)
  • When responding, each 4D server replies with a UDP unicast message from its address to the client's address with source port = 19813 and destination port = whatever port the client had used to broadcast.
  • So in order to let the client receive the answer back from the server, one has to punch a hole in the firewall for all UDP packets with a source port of 19813.

Manually configuring the mSupply client

Due to firewall or if you connect to mSupply server via a router, then you may need to enter in the IP address on the mSupply Client custom setting window.

The data base name is always : mSupply

If mSupply server is serving via the default port (19813) then simply enter in the IP address.

Register mSupply

The procedure is described earlier in “Preferences” chapter of the mSupply manual. See The Register button

You will either have to phone or email the information to Sustainable Solutions to obtain a registration code.

The registration code is keyed to your Organisation name and the MAC address of the server. Changing either of these will require a new code, which we shall willingly provide. So, take care when setting the Organisation Name!

Configure mSupply preferences

Once registered, you may want to systematically to go through the mSupply Preferences and choose appropriate settings, and particularly setting up the Secondary backups! Start here: Preferences > General

Turn off web dashboard

If the web dashboard has been set up on the Primary Server, then the dashboard preferences will be copied to the Satellite site datafile. In most cases, the web dashboard is not being used on the Satellite site and it is an unnecessary interaction with the scheduler, so may as well be turned off:

Before v4.04:

  1. File > Preferences… > Dashboard
  2. Untick the 'We use the web dashboard'
  3. Click OK

After v4.04, the dashboard is managed through the Admin page of the navigator:

  1. Admin > Dashboard > Export Settings
  2. Clear the Postgres Server entries
  3. Click OK

Turn off servers

The Primary Server runs one or more 'Servers'. The preferences controlling these will be copied to the Satellite site datafile. In most cases, these servers are not being used on the Satellite site and it is an unnecessary interaction with the scheduler, so may as well be turned off:

  • File > Preferences… > Server
    • Turn off any 'Servers'
Configure secondary backups

You should have already configured the primary backup. We recommend setting up a secondary backup which will send a backup off-site using a service such as Dropbox. The frequency of this depends largely on what bandwidth your site can afford. Each backup can easily get to GB sizes…:

  • File > Preferences… > Backup 2
    • Configure secondary backups

Turn on Syncronisation

When you are finally ready to turn on synchronisation:

  • File > Preferences… > Synchronise > Click to un-lock, enter code to edit.
    • Set the Sync time interval to 1
    • Click OK

Your installation of mSupply may have customisations made specifically for your work scenario. Please contact our support staff on support@msupply.org.nz to manage these customisations.

Configure label printer

If you are dispensing, you will need to set up label printer preferences

Upgrading to a newer version of mSupply

User Access Control, a feature of Windows 7, requires that the undernoted steps are followed when you are upgrading mSupply

  1. In Windows 7 click Start Menu> Control Panel> User Accounts
  2. Click 'Change User Account Control Settings'
  3. In the window that appears move the slider to the bottom and hit OK
  4. You will be requested to restart the computer - do so(!)
  5. If you copied the files already (which wont work as the pseudo copy occurs) these copied files should now automatically work

Graceful shutdown in the event of a power failure

Your mSupply server should be attached to a UPS. The UPS should be fitted with a control cable (serial, USB or network cable) that allows control software to detect a low power situation and shut down the server.

In the UPS control software set the shutdown to start at least two minutes before the power will fail.

Set it to run a batch file at that point. The file should contain the single line “net stop Service name” where the service name is the name displayed in the properties when you double-click the service name in the services window. In the example below the service name is “4DS mSupply.4DC” (not to be confused with the display name)

You may wish to test your typing skills by opening a command prompt:

Accessing a cloud hosted server

Access to a cloud hosted mSupply server is through the Windows Remote Desktop Protocol.

Windows client

If the mSupply client software is running on a PC, there are a range of applications that can be used for accessing the cloud hosted mSupply server including Microsoft's own Remote Desktop Connection software that comes included with Microsoft Windows. There are third party implementations that provide additional security and controls. One that we are currently (2016) finding effective is TS-Plus.

Macintosh client

Access to the the Microsoft Remote Desktop App is available on the Apple Store: https://itunes.apple.com/en/app/microsoft-remote-desktop/id715768417?mt=12

  • The Display Name is the name that will appear on your computer. We suggest you make it: mSupply Remote Access
  • The Computer Name is the name of the domain name of the mSupply server computer that you are connecting to.

  • Last modified: 2020/09/07 01:51
  • by Mark Glover