SafeKit quick installation guide with Apache (apache_farm.safe module with network load balancing and failover)

SafeKit quick installation guide with Apache on Windows and Linux

Package installation on Windows

Download the free version of SafeKit on 2 Windows nodes (or more).

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.

Package installation on Linux

Install the free version of SafeKit on 2 Linux nodes (or more).

Note: the free trial includes all SafeKit features. At the end of the trial, you can activate permanent license keys without uninstalling the package.
After the download of safekit_xx.bin package, execute it to extract the rpm and the safekitinstall script and then execute the safekitinstall script
Answer yes to firewall automatic configuration
Set the password for the web console and the default user admin.
1. Use aphanumeric characters for the password (no special characters).
2. The password must be the same on both nodes.

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.

In a farm architecture, you can define more than 2 nodes.

If you want, you can add a new LAN for a second heartbeat.

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 in Module startup at boot.
Normally, you have a single Heartbeat network (except if you add 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).
Set the service port to load balance (ex.: TCP 80 for HTTP, TCP 443 for HTTPS, TCP 9010 in the example).
Set the load balancing rule, Source address or Source port:
- with the source IP address of the client, the same client will be connected to the same node in the farm on multiple TCP sessions and retrieve its context on the node.
- with the source TCP port of the client, the same client will be connected to different nodes in the farm on multiple TCP sessions (without retrieving a context).
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.

5. Edit scripts (optional)

start_both and stop_both must contain starting and stopping of the Apache application (example provided for Microsoft IIS 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_both (SafeKit controls the start of services in start_both).

8. Wait for the transition to UP (green) / UP (green)

Node 1 and node 2 should reach the UP (green) state, which means that the start_both script has been executed on node 1 and node 2.

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

click the "log" icon of node1 or 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_both in the log: output messages of the script are displayed on the right and errors can be detected such as a service incorrectly started.

9. Testing

SafeKit brings a built-in test in the product:

Configure a rule for TCP port 9010 with a load balancing on source TCP port.
Connect an external workstation outside the farm nodes.
Start a browser on http://virtual-ip:9010/safekit/mosaic.html.

You should see a mosaic of colors depending on nodes answering to HTTP requests.

Stop one UP (green) node by scrolling down its contextual menu and clicking Stop.
Check that there is no more TCP connections on the stopped node and on the virtual IP address.

More information on tests in the User's Guide.

Internals

Internal files of a SafeKit / Apache load balancing cluster with failover

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

Internal files of the Windows apache_farm.safe module

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

<!DOCTYPE safe>
<safe>
<macro name="VIRTUAL_IP" value="VIRTUAL_IP_TO_BE_DEFINED" />
<macro name="APACHE_PORT" value="TCP_PORT_TO_BE_DEFINED" />
<service mode="farm" maxloop="3" loop_interval="24">
  <!-- Farm topology configuration for the membership protocol -->
  <!-- Names or IP addresses on the default network are set during initialization in the console -->
  <farm>
    <lan name="default" />
  </farm>
  <!-- Virtual IP Configuration -->
  <!-- Use VIRTUAL_IP defined in macro above -->
  <vip>
    <interface_list>
      <interface check="on" arpreroute="on">
        <virtual_interface type="vmac_directed">
          <virtual_addr addr="%VIRTUAL_IP%" where="alias"/>
        </virtual_interface>
      </interface>
    </interface_list>
    <loadbalancing_list>
      <group name="APACHE">
        <!-- Set load-balancing rule on APACHE_PORT defined in macro above -->
        <rule port="%APACHE_PORT%" proto="tcp" filter="on_addr"/>
      </group>
    </loadbalancing_list>
  </vip>
  <!-- TCP Checker Configuration -->
  <!-- Use VIRTUAL_IP and APACHE_PORT defined in macros above -->
  <check>
    <tcp ident="HTTP_APACHE" when="both">
      <to
         addr="%VIRTUAL_IP%"
         port="%APACHE_PORT%"
         interval="10"
         timeout="5"
       />
    </tcp>
  </check>
  <!-- User scripts activation -->
  <user nicestoptimeout="300" forcestoptimeout="300" logging="userlog" />
</service>
</safe>

start_both.cmd on Windows

@echo off

rem Script called on all servers for starting applications

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

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

set res=0

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

set res=%errorlevel%
if %res% == 0 goto end

:stop
set res=%errorlevel%
"%SAFE%\safekit" printe "start_both failed"

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

:end

stop_both.cmd on Windows

@echo off

rem Script called on all servers for stopping application

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_both %*" 

set res=0

rem default: no action on forcestop
if "%1" == "force" goto end

%SAFE%\safekit printi "Stopping Apache..."
net stop Apache2

rem If necessary, uncomment to wait for the real stop of services
rem "%SAFEBIN%\sleep" 10

if %res% == 0 goto end

"%SAFE%\safekit" printe "stop_both failed"

:end

Internal files of the Linux apache_farm.safe module

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

<!DOCTYPE safe>
<safe>
<macro name="VIRTUAL_IP" value="VIRTUAL_IP_TO_BE_DEFINED" />
<macro name="APACHE_PORT" value="TCP_PORT_TO_BE_DEFINED" />
<service mode="farm" maxloop="3" loop_interval="24">
  <!-- Farm topology configuration for the membership protocol -->
  <!-- Names or IP addresses on the default network are set during initialization in the console -->
  <farm>
    <lan name="default" />
  </farm>
  <!-- Virtual IP Configuration -->
  <!-- Use VIRTUAL_IP defined in macro above -->
  <vip>
    <interface_list>
      <interface check="on" arpreroute="on">
        <virtual_interface type="vmac_directed">
          <virtual_addr addr="%VIRTUAL_IP%" where="alias"/>
        </virtual_interface>
      </interface>
    </interface_list>
    <loadbalancing_list>
      <group name="APACHE">
        <!-- Set load-balancing rule on APACHE_PORT defined in macro above -->
        <rule port="%APACHE_PORT%" proto="tcp" filter="on_addr"/>
      </group>
    </loadbalancing_list>
  </vip>
  <!-- TCP Checker Configuration -->
  <!-- Use VIRTUAL_IP and APACHE_PORT defined in macros above -->
  <check>
    <tcp ident="HTTP_APACHE" when="both">
      <to
         addr="%VIRTUAL_IP%"
         port="%APACHE_PORT%"
         interval="10"
         timeout="5"
       />
    </tcp>
  </check>
  <!-- User scripts activation -->
  <user nicestoptimeout="300" forcestoptimeout="300" logging="userlog" />
</service>
</safe>

start_both on Linux

#!/bin/sh 
# Script called on the primary server for starting applications 

# For logging into SafeKit log use:
# $SAFE/safekit printi | printe "message" 

#---------- Clean Apache residual processes 
# Call this function before starting Apache 
# to clean eventual resual Apache processes
clean_Apache()
{
  retval=0

  # $SAFE/safekit printw "Cleaning Apache processes"

  # example of a kill of started Apache process
  # warning: this command also kills the httpd process which managed the SafeKit web console
  # ps -e -o pid,comm | grep httpd | $AWK '{print "kill " $1}'| sh >/dev/null 2>&1

  return $retval
}

#---------- Apache
# Call this function for starting Apache Server
start_Apache()
{
  retval=0

  $SAFE/safekit printw "Starting Apache Server"

  # Apache - Starting 
  service httpd start   
  if [ $? -ne 0 ] ; then 
    $SAFE/safekit printw "Apache server start failed"
  else
    $SAFE/safekit printw "Apache server started"
  fi

  return $retval
}

# stdout goes into Application log
echo "Running start_both $*" 

res=0

[ -z "$OSNAME" ] && OSNAME=`uname -s`
OSNAME=`uname -s`
case "$OSNAME" in
    Linux)
	AWK=/bin/awk
	;;
    *)
	AWK=/usr/bin/awk
	;;
esac

# TODO
# remove Apache boot start 

# Clean Apache residual processes 
clean_Apache || res=$?

# Start Apache
start_Apache || res=$?

if [ $res -ne 0 ] ; then
  $SAFE/safekit printi "start_both failed"

  # uncomment to stop SafeKit when critical
  # $SAFE/safekit stop -i "start_both"
fi

exit 0

stop_both on Linux

#!/bin/sh
# Script called on the primary server for stopping application services

# For logging into SafeKit log use:
# $SAFE/safekit printi | printe "message" 

#----------------------------------------------------------
#
# 2 stop modes:
#
# - graceful stop
#   call standard application stop
#
# - force stop ($1=force)
#   kill application's processes
#
#----------------------------------------------------------

#---------- Clean Apache residual processes
# Call this function on force stop 
# to clean eventual resual Apache processes 
clean_Apache()
{
  retval=0

  # $SAFE/safekit printw "Cleaning Apache processes "

  # example of a kill of started Apache process
  # warning: this command also kills the httpd process which managed the SafeKit web console
  # ps -e -o pid,comm | grep httpd | $AWK '{print "kill " $1}'| sh >/dev/null 2>&1

  return $retval
}

#---------- Apache
# Call this function for stopping Apache
stop_Apache()
{
  retval=0

  if [ "$1" = "force" ] ; then
    # Apache force stop
    clean_Apache
    return $retval
  fi

  # Apache graceful stop
  $SAFE/safekit printw "Stopping Apache server"  
  service httpd stop
  if [ $? -ne 0 ] ; then 
    $SAFE/safekit printw "Apache server stop failed"
  else
    $SAFE/safekit printw "Apache server stopped"  
  fi

  return $retval
}

# stdout goes into Application log
echo "Running stop_both $*" 

res=0

[ -z "$OSNAME" ] && OSNAME=`uname -s`
case "$OSNAME" in
    Linux)
	AWK=/bin/awk
	;;
    *)
	AWK=/usr/bin/awk
	;;
esac

mode=
if [ "$1" = "force" ] ; then
  mode=force
  shift
fi

# Stop Apache  server 
stop_Apache $mode || res=$?

[ $res -ne 0 ] && $SAFE/safekit printi "stop_both failed"

exit 0