SafeKit quick installation guide with Milestone XProtect Management Server (milestone.safe mirror module)

Overview of the solution

SafeKit quick installation guide for Milestone and SQL

Prerequisites

You need Milestone XProtect and SQL installed on 2 nodes (virtual machines or physical servers). SQL Server can be external, see the note below.
On Windows, with Windows services manager, put Milestone XProtect and SQL services with Boot Startup Type = Manual on both nodes. SafeKit controls start of Milestone XProtect and SQL services in start_prim. Edit start_prim during the configuration to check if you have put all services in Manual boot including the new ones that you can add.

Note: SQL Server can be external. In this case, at step 4 during the step by step configuration of milestone.safe:

remove the replication of SQL Data\ and Log\ folders,
remove the process checker on sqlservr.exe,
remove the start and stop of the MSSQLServer service in start_prim and stop_prim scripts.

You can implement redundancy of the external SQL Server with SafeKit and the sqlserver.safe module.

In this case on both management nodes, configure the connection of Milestone Management to SQL with the virtual IP address of the sqlserver.safe module (registry key HKEY_LOCAL_MACHINE\SOFTWARE\VideoOS\Server\ConnectionString).

Note: The Event server can be external to the Management server.

In this case, you have 2 clusters with 2 installations of milestone.safe: one for the Management cluster, the other one for the Event cluster.

For the Management cluster, at step 4 during the step by step configuration of milestone.safe:

remove the start and stop of "MilestoneEventServerService" in start_prim and stop_prim scripts.

And for the Event cluster, at step 4 during the step by step configuration of milestone.safe:

remove the start and stop of "Milestone XProtect Management Server" and "Milestone XProtect Log Server" in start_prim and stop_prim scripts,
remove the start and stop of the MSSQLServer service in start_prim and stop_prim scripts,
remove the replication of SQL Data\ and Log\ folders,
remove the process checker on sqlservr.exe,
during the step-by-step configuration, register the Event server with the virtual IP address of the Management cluster (or install the Event server from the Download Manager and set the virtual IP address of the Management cluster during the installation),
in the Milestone management client, set the Event Server with the virtual IP address of the Event cluster in the Registered Services.

In case of migration of Milestone from version N to version N+1 in a SafeKit cluster, read this article: Milestone Management Migration with SafeKit

Package installation on Windows

Download the free version of SafeKit on 2 Windows nodes.

Note: the free version includes all SafeKit features. At the end of the trial, you can activate permanent license keys without uninstalling the package.
To open the Windows firewall, on both nodes start a powershell as administrator, and type
```
c:/safekit/private/bin/firewallcfg add
```
To initialize the password for the default admin user of the web console, on both nodes start a powershell as administrator, and type
```
c:/safekit/private/bin/webservercfg.ps1 -passwd pwd
```
1. Use aphanumeric characters for the password (no special characters).
2. pwd must be the same on both nodes.
Exclude from antivirus scans C:\safekit\ (the default installation directory) and all replicated folders that you are going to define.

Antiviruses may face detection challenges with SafeKit due to its close integration with the OS, virtual IP mechanisms, real-time replication and restart of critical services.

Step by step configuration

2. Configure node addresses

Enter the node IP addresses, press the Tab key to check connectivity and fill node names.
Then, click on Save and apply to save the configuration.

If either node1 or node2 has a red color, check connectivity of the browser to both nodes and check firewall on both nodes for troubleshooting.

If you want, you can add a new LAN for a second heartbeat and for a dedicated replication network.

This operation will place the IP addresses in the cluster.xml file on both nodes (more information in the training with the command line).

4. Configure the module

Choose an Automatic start of the module at boot without delay.
Normally, you have a single Heartbeat network on which the replication is made. But, you can define a private network if necessary (by adding a LAN at step 2).
Enter a Virtual IP address. A virtual IP address is a standard IP address in the same IP network (same subnet) as the IP addresses of both nodes.
Application clients must be configured with the virtual IP address (or the DNS name associated with the virtual IP address).
The virtual IP address is automatically switched in the event of a failure.
Check that the Replicated directories are installed on both nodes and contain the application data.
Data and log replication are essential for a database..
You can create additional replicated directories as required.
Note that if a process name is displayed in Monitored processes/services, it will be monitored with a restart action in case of failure. Configuring a wrong process name will cause the module to stop right after its start.

If SQL is on the management server:

The SQL system databases (like master.mdf and mastlog.ldf) must be located in the same directories on both nodes. The directories must be configured as replicated.
SQL must be also installed at the same location in the file system on both nodes because the read-only SQL resource database is located in the binary and is required for the failover. This database does not need to be replicated.
The SQL Milestone databases (.mdf and .ldf) must be located in the same directories on both nodes. The directories must be configured as replicated. Milestone databases are as follows according this article.

If you click on Advanced configuration, the userconfig.xml file is displayed (example with Microsoft SQL Server).

5. Edit scripts (optional)

start_prim and stop_prim must contain starting and stopping of the Milestone XProtect and SQL application (example provided for Microsoft SQL Server on the right).
You can add new services in these scripts.
Check that the names of the services started in these scripts are those installed on both nodes, otherwise modify them in the scripts.
On Windows and on both nodes, with the Windows services manager, set Boot Startup Type = Manual for all the services registered in start_prim (SafeKit controls the start of services in start_prim).

9. Start the node with up-to-date data

If node 1 has the up-to-date replicated directories, select it and start it As primary.

When node 2 will be started, all data will be copied from node 1 to node 2.

If you make the wrong choice, you run the risk of synchronizing outdated data on both nodes.

It is also assumed that the Milestone XProtect and SQL application is stopped on node 1 so that SafeKit installs the replication mechanisms and then starts the application in the start_prim script.

Use Start for subsequent starts: SafeKit retains the most up-to-date server. Starting As primary is a special start-up the first time or during exceptional operations.

10. Wait for the transition to ALONE (green)

Node 1 should reach the ALONE (green) state, which means that the virtual IP is set and that the start_prim script has been executed on node 1.

If ALONE (green) is not reached or if the application is not started, analyze why with the module log of node 1.

click the "log" icon of node1 to open the module log and look for error messages such as a checker detecting an error and stopping the module.
click on start_prim in the log: output messages of the script are displayed on the right and errors can be detected such as a service incorrectly started.

If the cluster is in WAIT (red) not uptodate, STOP (red) not uptodate state, stop the WAIT node and force its start as primary.

11. In the desktop of node 1, stop, then register on the vitual IP address and restart the Milestone Management Server

Execute the following bullets on node 1 according the menu in the image:

Right-click on the Milestone Management Server icon in the taskbar.
Stop Management Server Service
Then choose Server Configurator... and register the virtual IP address.
Start Management Server Service

This procedure registers the node 1 management server in the SQL database (running on node 1) through a connection to the virtual address.

12. Solve Windows authentication issue on failover

When you start the Milestone XProtect Management Client, you have to authenticate either with "Windows authentication" or "Basic authentication" (click here to see the screenshot).

If Milestone "Windows authentication" has been configured with an Active Directory, the user/password will be retrieved in the external AD on the secondary node after a failover, so there is no special configuration.

Open Milestone XProtect Management Client and in Security / Roles (see image)

Set the Windows BUILTIN\Administrators group.

Warning

By setting the BUILTIN\Administrators group, you will be able to authenticate on the seconday node with a local Windows administrator on failover.

Else no authentication will be possibe with a local Windows account on the secondary after a failover.

It's because the BUILTIN\Administrators group has the same SID on both nodes. For other local groups or local users, authentication will not be possible on the secondary because SIDs are different between both nodes even if they have the same name.

Create a user with a "Basic authentication" (Admin in the image) to be sure to re-authenticate on the secondary node after a failover. For "Basic authentication", the user/password is stored in the SQL database and will be retrieved on the secondary node after a failover.

13. In the desktop of node 2, register the management server on the vitual IP address

Choose Server Configurator in the taskbar of node 2 and register it on the virtual IP address (see image).
Then Stop Management Server Service.

The account of the user executing the registration on node 2 must have the administrator role in Milestone on node 1.

If it is the local administrator on node 2 who makes the registration, the built-in Windows group BUILTIN\Administrators must have been set in Management Client / Security / Roles at Step 12. Else the registration will not work.

This procedure registers the node 2 management server in the SQL database (running on node 1) through a connection to the virtual address.

15. Verify that the cluster is operational

Check that the cluster is green/green with Milestone XProtect and SQL services running on the PRIM node and not running on the SECOND node.
Only changes inside files are replicated in real time in this state.

Register the recording servers with the virtual IP address.
Connect the Milestone Management Client and the Milestone Smart Client on the virtual IP address.

Components that are clients of Milestone XProtect and SQL services must be configured with the virtual IP address. The configuration can be done with a DNS name (if a DNS name has been created and associated with the virtual IP address).

16. Testing

Stop the PRIM node by scrolling down its contextual menu and clicking Stop.
Verify that there is a failover on the SECOND node which should become ALONE (green).
And with Microsoft Management Console (MMC) on Windows or with command lines on Linux, check the failover of Milestone XProtect and SQL services (stopped on node 1 in the stop_prim script and started on node 2 in the start_prim script).

If ALONE (green) is not reached on node2 or if the application is not started, analyze why with the module log of node 2.

click the "log" icon of node2 to open the module log and look for error messages such as a checker detecting an error and stopping the module.
click on start_prim in the log: output messages of the script are displayed on the right and errors can be detected such as a service incorrectly started.

If everything is okay, initiate a start on node1, which will resynchronize the replicated directories from node2.

If things go wrong, stop node2 and force the start as primary of node1, which will restart with its locally healthy data at the time of the stop.

More information on tests in the User's Guide.

18. If necessary, configure a splitbrain checker

See below "What are the different scenarios in case of network isolation in a cluster?" to know if you need to configure a splitbrain checker.
Go to the module configuration and click on Checkers / Splitbrain (see image) to edit the splitbrain parameters.
Save and apply the new configuration to redeploy it on both nodes (module must be stopped on both nodes to save and apply).

Parameters:

Resource name identifies the witness with a resource name: splitbrain.witness. You can change this value to identify the witness.
Witness address is the argument for a ping when a node goes from PRIM to ALONE or from SECOND to ALONE. Change this value with the IP of the witness (a robust element, typically a router).
Note: you can set several IPs separated by white spaces. Pay attention that the IP addresses must be accessible from one node but not from the other in the event of network isolation.

When there is a network isolation, the behavior with a split-brain checker is:

a split-brain checker has been configured with the IP address of a witness (typically a router),
the split-brain checker operates when a server goes from PRIM to ALONE or from SECOND to ALONE,
in case of network isolation, before going to ALONE, both nodes test the IP address,
the node which can access the IP address goes to ALONE, the other one goes to WAIT,
when the isolation is repaired, the WAIT node resynchronizes its data and becomes SECOND.

Note: If the witness is down or disconnected, both nodes go to WAIT and the application is no more running. That's why you must choose a robust witness like a router.

Internals

Internals of a SafeKit / Milestone XProtect and SQL high availability cluster with synchronous replication and failover

Go to the Advanced Configuration tab in the console, for editing these files

Internal files of milestone.safe module

userconfig.xml (description in the User's Guide)

<!DOCTYPE safe>
<safe>
<service mode="mirror">
  <!-- Heartbeat Configuration -->
  <!-- Names or IP addresses on the default network are set during initialization in the console -->
  <heart>
    <heartbeat name="default">
    </heartbeat>
  </heart>
  <!-- Virtual IP Configuration -->
  <!-- Define the name or IP address of your virtual server 
  -->
  <vip>
    <interface_list>
        <interface> 
	  <real_interface>
               <virtual_addr addr="VIRTUAL-IP-ADDRESS" where="one_side_alias" />
          </real_interface>
        </interface>
    </interface_list>
  </vip>
  <!-- Software Error Detection Configuration -->
  <errd polltimer="10">
    <!-- SQL Server process -->
    <proc name="sqlservr.exe" atleast="1" action="restart" class="prim" />
  </errd>
  <!-- File Replication Configuration -->
  <!-- Adapt with the directory of your SQL Server database and logs
  -->
  <rfs>
	<replicated dir="C:\Program Files\Microsoft SQL Server\MSSQL15.MSSQLSERVER\MSSQL\DATA" mode="read_only" />
	<replicated dir="C:\Program Files\Microsoft SQL Server\MSSQL15.MSSQLSERVER\MSSQL\Log" mode="read_only" />
  </rfs>
  <!-- User scripts activation -->
  <user />
</service>
</safe>

start_prim.cmd

@echo off

rem Script called on the primary server for starting application services 

rem For logging into SafeKit log use:
rem "%SAFE%\safekit" printi | printe "message"

rem stdout goes into Application log
echo "Running start_prim %*" 

set res=0

rem TODO: set to manual the start of services when the system boots
sc.exe config MSSQLSERVER start= demand

net start "W3SVC"

for /F "usebackq tokens=*" %%A in ("%SAFEUSERBIN%\apppoollist.txt") do %systemroot%\system32\inetsrv\appcmd start apppool /apppool.name:"%%A"
if not %errorlevel% == 0 (
  "%SAFE%\safekit" printi "Application Pools start failed"
) else (
  "%SAFE%\safekit" printi "Application Pools started"
)

net start "MSSQLServer"
if not %errorlevel% == 0 (
  %SAFE%\safekit printi "SQL Server (MSSQLServer) start failed"
) else (
  %SAFE%\safekit printi "SQL Server (MSSQLServer) started"
)

"%SAFEBIN%\sleep" 10

net start "Milestone XProtect Management Server"
if not %errorlevel% == 0 (
  %SAFE%\safekit printi "Milestone XProtect Management Server start failed"
) else (
  %SAFE%\safekit printi "Milestone XProtect Management Server started"
)

"%SAFEBIN%\sleep" 10

net start "Milestone XProtect Log Server"
if not %errorlevel% == 0 (
  %SAFE%\safekit printi "Milestone XProtect Log Server start failed"
) else (
  %SAFE%\safekit printi "Milestone XProtect Log Server started"
)

net start "MilestoneEventServerService"
if not %errorlevel% == 0 (
  %SAFE%\safekit printi "MilestoneEventServerService start failed"
) else (
  %SAFE%\safekit printi "MilestoneEventServerService started"
)

net start "Milestone XProtect Data Collector Server"
if not %errorlevel% == 0 (
  %SAFE%\safekit printi "Milestone XProtect Data Collector Server start failed"
) else (
  %SAFE%\safekit printi "Milestone XProtect Data Collector Server started"
)

set res=%errorlevel%

if %res% == 0 goto end

:stop
"%SAFE%\safekit" printe "start_prim failed"

rem uncomment to stop SafeKit when critical
rem "%SAFE%\safekit" stop -i "start_prim"

:end

stop_prim.cmd

@echo off

rem Script called on the primary server for stopping application services 

rem For logging into SafeKit log use:
rem "%SAFE%\safekit" printi | printe "message"

rem ----------------------------------------------------------
rem
rem 2 stop modes:
rem
rem - graceful stop
rem   call standard application stop with net stop
rem
rem - force stop (%1=force)
rem   kill application's processes
rem
rem ----------------------------------------------------------

rem stdout goes into Application log
echo "Running stop_prim %*" 

set res=0

rem default: check mssql stopped on forcestop
if "%1" == "force" goto check

%SAFE%\safekit printi "Stopping Milestone XProtect Corporate Data Collector Server"
net stop "Milestone XProtect Data Collector Server" /Y

%SAFE%\safekit printi "Stopping Milestone Event Server Service"
net stop "MilestoneEventServerService" /Y

%SAFE%\safekit printi "Stopping Milestone Log Server Service"
net stop "Milestone XProtect Log Server" /Y

%SAFE%\safekit printi "Stopping Milestone XProtect Corporate Management Server"
net stop "Milestone XProtect Management Server" /Y

%SAFE%\safekit printi "Stopping SQL Server (MSSQLSERVER)"
sc.exe config "MSSQLSERVER" start= disabled
net stop "MSSQLSERVER" /Y

"%SAFEBIN%\sleep" 10

net stop "W3SVC" /Y

rem Wait a little for the real stop of services
"%SAFEBIN%\sleep" 10

if %res% == 0 goto end

"%SAFE%\safekit" printe "stop_prim failed"
goto end

:check
rem call :checksrv "MSSQLSERVER"
goto end

:checksrv
  set SERVICE=%1
  net stop %SERVICE% /Y
  if NOT ERRORLEVEL 1 goto end
  sc query state= inactive | findstr /C:%SERVICE% 
  if NOT ERRORLEVEL 1 goto end
  "%SAFE%\safekit" stop -i "stop_prim: service not stopped"
  exit

:end