Skip to main content
Skip table of contents

Installing Imagicle SimpleFailover

This KB article applies to Imagicle UCX on-prem Suite owners. If your Imagicle UCX Suite is deployed in the Cloud, Imagicle HA is included and does not require additional configurations.

Applies to:

Imagicle UCX Suite any release on Windows Server 2012 and above.

Description:

This article explains what is the Imagicle SimpleFailover application and the required steps to install it on every node belonging to an Imagicle cluster. 

What is the Imagicle SimpleFailover

Imagicle SimpleFailover is an application that issues one or more polling requests (e.g. HTTP GET to a specific page) to verify if one or more services are up or not on different Imagicle UCX nodes (typically all nodes belonging to a cluster). Based on the results of these polls, it updates the IP of one or more DNS entries in the Windows DNS service. It leverages Windows DNS to manage DNS requests from remote clients, so it is not itself a DNS server. 

In the image below, is it possible to see requests flow within a single Imagicle node:

image-20250113-133041.png

Instead, this is the general schema:

image-20250113-133059.png

Known Limitations

Web browsers implement an internal DNS cache that may be up to 30 minutes. Such cache makes the client insensitive to above described failover mechanism, so a connection attempt might be sent to the unavailable server. The client can connect to the available server only when its internal DNS cache has expired.
To override this problem on web browser or Jabber/Webex/MS-Teams gadgets, please restart the client to clean DNS cache.

How to install it

To install the Imagicle SimpleFailover, there are some tasks Imagicle should perform:

  • configuration of the Domain DNS Server: we need this to forward DNS requests for a specific sub-domain (e.g., *.imagicle.mycompany.com) to one of the nodes in the Imagicle cluster

  • on every Imagicle node:

    • (two steps below are done automatically through the installation script)

    • installation and configuration of the Windows DNS Server role

    • installation and startup of the Imagicle SimpleFailover

Before proceeding with the installation/configuration, please make sure these configurations have been already done:

  • installation of all Imagicle nodes

  • configuration of all Imagicle nodes

  • configuration of the Imagicle cluster

Domain DNS Server configuration

We have to configure the Domain DNS Server in order to forward relevant DNS requests (like ucx.imagicle.mycompany.com) to the local DNS Servers available on Imagicle nodes.

On the Domain DNS Server, open the DNS application and create a new Zone dedicated for Imagicle (e.g. imagicle.mycompany.com)

Open the DNS Manager and click on Action --> New Zone

image-20250113-133113.png

then select "Primary zone"

image-20250113-133126.png

and "Forward lookup zone"

image-20250113-133139.png

now enter the relevant Zone Name (e.g. imagicle.mycompany.com)

image-20250113-133153.png

then confirm the default settings and complete the zone’s creation. At the end you should have the new zone listed under the Forward Lookup Zones:

image-20250113-133212.png

Now right-click on the created Zone and select “New Delegation”

image-20250113-133228.png

as a Delegated Domain Name add *, because we want to delegate the resolution of the whole *.imagicle.mycompany.com sub-domain

image-20250113-133245.png

on the next screen, we have to add IPs of the servers delegated to resolve *.imagicle.mycompany.com sub-domain. So, click on Add

image-20250113-133257.png

add all the UCX Suite nodes’ IPs and then click OK and confirm the configuration

image-20250113-133311.png

Finally, confirm all the settings and complete the configuration. At the end you should have something like this:

image-20250113-133325.png

Now, the Domain DNS Server is configured.

Imagicle SimpleFailover installation

The procedure below must be done all Imagicle nodes belonging to the cluster.

In order to install the tool we have to:

  • install Nodejs

  • unzip application folders

  • execute a couple of Powershell scripts

All needed tools are available here. Before to start, copy the Imagicle SimpleFailover zip file to the Imagicle node.

Let’s start with the Nodejs installation, so extract from the zip archive the file node-<version>.msi and execute it. Installation is pretty straightforward, just next, next, next.

Now, create the "custom" folder within the UCX Suite installation folder. Default is C:\Program Files (x86)\StonevoiceAS):

<UCS_FOLDER>\custom

and unzip the archive into it. At the end, you should have this situation:

<UCS_FOLDER>\custom\ImagicleSimpleFailover
<UCS_FOLDER>\custom\pm2-installer-main

Now open Powershell as an administrator and execute this command:

cd "<UCS_FOLDER>\custom\pm2-installer-main\service_scripts\"

Now we have to run the installation script, passing these 3 mandatory arguments:

  • zoneName: Zone Name to be configured on the local DNS Server (e.g. imagicle.mycompany.com)

  • hostname: name of the host on the local DNS Server to modify (e.g. ucx)

  • domainDNSServer: Domain DNS Server’s IP

this is the installation script:

.\install.ps1 -zoneName imagicle.mycompany.com -hostname ucx -domainDNSServer 192.168.1.2

if one of them is missing, the installation process will ask you to do the "Standard installation", in that case you have to abort it, entering "n" or pressing "ctrl+c". Don't proceed the "Standard installation", because it supposes to do some configurations manually.

If everything is ok, you will be prompted to confirm the "Smart installation", just press Enter (default is yes)

Params zoneName, hostname and domainDNSServer are available. Do you want to proceed with Smart Installation? [y/n][default:y]: y

The installation process will start, executing all the required operations. For your information, the installation doesn't need internet connection.

When the process terminates, execute this script to start the Imagicle SimpleFailover:

.\startApp.ps1

You should see an output like below sample:

image-20250113-133348.png

Try to connect to the Imagicle SimpleFailover dashboard from the local server (only access from localhost is granted), default url is http://localhost:81.
You can also try from another server to point to ucx.imagicle.mycompany.com, you should be able to reach the primary node.
If you want to try out the fallback to one of the secondary nodes, you can stop IIS on the master node and see if DNS are updated correctly. To do this test, open Powershell on the master node and run this command:

iisreset /stop

then wait some seconds (by default the check is done every 30 seconds when all nodes are OK). You should see on the dashboard the local node status updated to KO. After that, try again to point to ucx.imagicle.mycompany.com from another pc and you should be able to reach one of the secondary nodes.
After that, start again IIS on the master node:

iisreset /start

and verify from the Imagicle SimpleFailover dashboard that now all the nodes are OK.

You can now close Powershell, the installation is completed.

Additional Configurations to leverage new DNS entry

Ensure that all users access to Imagicle web portal by using the virtual hostname above defined, like: https://ucs.imagicle.mycompany.com

Ensure that all Imagicle-related CUCM XML Phone Services are including the virtual hostname. See below samples:

Phonelock Service URL: http://ucs.imagicle.mycompany.com/fw/Apps/Stonelock/xml/lock/default.aspx

Contact Manager Service URL: http://ucs.imagicle.mycompany.com/fw/Apps/Speedy/xml/directories/default.aspx

Finally, please ensure that Cisco IP Phones are configured to leverage customer's DNS server.

Configuration

Dashboard

Imagicle SimpleFailover has a built-in web dashboard, that can be used to see the status of the all the nodes, based on the results of the configured pollings. The dashboard is accessible only form localhost, pointing to http://localhost:81.

image-20250113-133405.png

The web page is automatically refreshed every 60s. 

Email notifications

Email notifications are enabled by default and they are sent when one of these events happens:

  • polling failure: when the polling fails and the previous polling was successful

  • polling success: when the polling succeed and the previous polling was failed

  • DNS update failure: when there is a failure in DNS updating 

The Outgoing emails configuration is taken from the UCX Suite. You can see how to configure it here.

The recipient list is taken from the Monitoring service configuration on the UCX Suite. More information are available here

If you change the outgoing emails parameters or the recipient list, you have to restart the Imagicle SimpleFailover:

  • access every Imagicle nodes through a Remote Desktop session

  • open Powershell

  • execute these commands
    cd "<UCX_FOLDER>\custom\pm2-installer-main\service_scripts\"
    ./restartApp.ps1

Configuration tests

  1. From any user's PC, please open the web browser and enter the URL including DNS name: https://ucx.imagicle.mycompany.com    The Imagicle UCX Suite login page should appear.

  2. From any IP Phone, access to Imagicle Phone Services. Verify the service is properly working.

  3. Turn off the Imagicle primary server or disconnect it from the network. Wait a couple of minutes.

  4. Restart web browser and repeat test #1. The UCX Suite login page should still be reachable

  5. Repeat test #2 (IP Phone Service access)

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.