---
canonical: https://safekit.evidian.com/wp-content/uploads/downloads_safekit/version-82/safekituserguidehtml/documentation/safekituserguideen.htm
---

## 15.6          Ping checker example

Below is an example of the configuration of
a ping checker in a mirror module. This checker tests that 192.168.1.1responds to the ping. If the ping
fails, the checker sets the resource **ping.**router to down. The
associated failover rule, named **p\_**router, executes a wait on the module when the resource goes down. 

|  |  |
| --- | --- |
| Commentaire, ajouter contour | ·         The resource name prefix is **ping.**  ·         The failover rule name prefix is **p\_**  ·         The suffix is the value of the attribute ident |

 

For a description of checkers, refer to section 13.11.3.

To test the ping checker, refer to section 4.4.5.

|  |  |
| --- | --- |
| To start the module configuration wizard, refer to section 3.3.  Switch to “Advanced configuration” to edit the XML if needed. | <!DOCTYPE safe>  <safe>  <service mode="mirror" boot="on">   <heart>    <heartbeat name="default">    </heartbeat>   </heart>   <vip>    <interface\_list>     <interface check="on">      <real\_interface>       <virtual\_addr addr="10.1.0.126" where="one\_side\_alias" check="on"/>      </real\_interface>     </interface>    </interface\_list>   </vip>   <rfs>    <replicated dir="e:\repdir"/>   </rfs>   <user></user>   <check>    <ping ident="**router**" when="pre" action="**wait**">      <to addr="**192.168.1.1**"/>    </ping>   </check>  </service>  </safe>  For details on XML configuration of <ping>, see section 13.13. |

 

## 15.7          Custom checker example with customchecker.safe

The customchecker.safe
module is a demonstration mirror module including a custom checker that tests
the presence of a file on the primary server. This feature is also available in
a farm module.

If the file is not present, the checker
sets the resource **custom.**checkfile
to down. The associated failover rule, named **c\_**checkfile, executes a
restart of the module when the resource goes down. 

|  |  |
| --- | --- |
| Commentaire, ajouter contour | ·         The resource name prefix is **custom.**  ·         The failover rule name prefix is **c\_**  ·         The suffix is the value of the attribute ident |

 

The customchecker.safe is
delivered with the SafeKit package and can be used as a basis for writing your
own checker.

For a description of checkers, refer to section 13.11.3.

To test the custom checker, refer to section 4.4.7 and section 4.4.8.

|  |  |
| --- | --- |
| Commentaire, ajouter contour | The following description is for Windows. For Linux, please refer to customchecker.safe delivered with the Linux package that includes Linux configuration and scripts. |

### 15.7.1      Module configuration with custom checker

The following example is the custom checker
configuration supported since SafeKit 8 with the attribute action.

|  |  |
| --- | --- |
| To start the module configuration wizard, refer to section 3.3.  Switch to “Advanced configuration” to edit the XML if needed. | <!DOCTYPE safe>  <safe>  <service mode="mirror" boot="on">   <heart>    <heartbeat name="default">    </heartbeat>   </heart>   <vip>    <interface\_list>     <interface check="on">      <real\_interface>       <virtual\_addr addr="10.1.0.126" where="one\_side\_alias" check="on"/>      </real\_interface>     </interface>    </interface\_list>   </vip>   <rfs>    <replicated dir="e:\repdir"/>   </rfs>   <user></user>   <check>     <custom ident="**checkfile**" exec="**checker.ps1**" arg="**c:\safekit\checkfile**" when="prim" action="**restart**"/>   </check>  </service>  </safe>  For details on XML configuration of <custom>, see section 13.16. |

 

The custom checker configuration for
SafeKit < 8 is still supported. In previous releases, the custom checker
configuration required to define an explicit failover rule in userconfig.xml as follow:

…  
<check>

 <custom ident="checkfile"
exec="checker.ps1" arg="c:\safekit\checkfile"
when="prim"/>

</check>

<failover>

 <![CDATA[

   c\_checkfile: if( custom.checkfile == down ) then
restart();

 ]]>

</failover>

…

Attribute action is not defined and its
value, by default, is noaction.

The module configuration wizard do not
present the failover section. You must switch to “Advanced configuration” to edit it.

### 15.7.2      Advanced configuration of module checker script

The custom checker is an infinite loop that
performs a test and assigns the associated resource as up or down based
on the test result.

The checker is called with at least 2
arguments:

·        
The 1st argument is the module name

·        
The 2nd is the name of the resource to be
assigned

If the <custom>
configuration contains the arg attribute, its value is passed as the next arguments.

In the following example, the checker is
written with the following precautions:

·        
The resource is only assigned if its value has
changed

·        
When the resource is down, the checker
consolidates this state (grace times) before assigning it. This can help to avoid false error
detections.

|  |  |
| --- | --- |
| Switch to “Advanced configuration” to list and edit all scripts. | # Custom checker template that tests if a file exists     param([Parameter(Mandatory = $true, ValueFromPipeLine = $true, position=1)][String]$ModName,        [Parameter(Mandatory = $true, ValueFromPipeLine = $true, position=2)][String]$RName,        [Parameter(Mandatory = $true, ValueFromPipeLine = $true, position=3)][String]$Arg1Value,        [Parameter(Mandatory = $false, ValueFromPipeLine = $false, position=4)][String]$Grace="2",        [Parameter(Mandatory = $false, ValueFromPipeLine = $false, position=5)][String] $Period="5"        )  # return up on success | down on failure  Function test([String]$Arg1Value)  {    $res="down"    if (Test-Path "$Arg1Value"){      $res="up"    }    return $res  }     $customchecker=$MyInvocation.MyCommand.Name  $safekit="$env:SAFE/safekit.exe"  $gracecount=0  $prevrstate="unknown"  # wait a little  Start-Sleep $Period     while ($true){    Start-Sleep $Period    $rstate = test($Arg1Value)    if($rstate -eq "down"){      $gracecount+=1    }else{      $gracecount = 0      if($prevrstate -ne $rstate){        & $safekit set -r "$RName" -v $rstate -i $customchecker -m $ModName        $prevrstate = $rstate      }     }     if($gracecount -ge $Grace){       if($prevrstate -ne $rstate){         & $safekit set -r "$RName" -v $rstate -i $customchecker -m $ModName         $prevrstate = $rstate        }        $gracecount = 0     }         }  Note the call to safekit set -r custom.checkfile -v up (or down) to assign the resource value.  Refer to section 9.3 for the description of this command. |

## 15.8          Split-brain checker example

Below is an example of the split-brain
checker configuration in a mirror module. This feature is not also available in
a farm module

This checker tests if the address 192.168.1.1 responds to the ping. If the ping fails, the checker sets the **splitbrain**.witness
resource to down.  
In case of network isolation between nodes, the split-brain checker assigns the
**splitbrain**.uptodate
resource as up or down according to access to the witness. The static and predefined
failover rule, named splitbrain\_failure, executes a wait on the module when this resource goes down. This ensures
that only the node with access to the witness becomes ALONE, while the
other is stuck in the WAIT state.

|  |  |
| --- | --- |
| Commentaire, ajouter contour | ·         The resource name prefix is **splitbrain.**  ·         The suffix is the value of the attribute ident  ·         The failover rule is static and predefined, and tests the other resource managed by the split-brain checker, splitbrain.uptodate. Its name is splitbrain\_failure. |

 

|  |  |
| --- | --- |
| To start the module configuration wizard, refer to section 3.3.  Switch to “Advanced configuration” to edit the XML if needed. | <!DOCTYPE safe>  <safe>  <service mode="mirror" boot="on">   <heart>    <heartbeat name="default">    </heartbeat>   </heart>   <vip>    <interface\_list>     <interface check="on">      <real\_interface>       <virtual\_addr addr="10.1.0.126" where="one\_side\_alias" check="on"/>      </real\_interface>     </interface>    </interface\_list>   </vip>   <rfs>    <replicated dir="e:\repdir"/>   </rfs>   <user></user>   <check>    <check>      <splitbrain ident="**witness**" exec="ping" arg="**10.1.0.112**"/>    </check>   </check>  </service>  </safe>  For details on XML configuration of <splitbrain>, see section 13.18. |

 

## 15.9          Module checker examples

### 15.9.1      Example of a farm module depending on a mirror module

Below is an example of the configuration of
a module checker in a farm module. This checker tests that the module name mirror
with virtual IP address 10.0.0.129
is ready (ALONE or PRIM). If it is not ready, the checker sets the resource **module.**mirror\_10.0.0.129 to down. The static and predefined failover rule, named module\_failure, executes a wait on the farm module when this resource goes down.

|  |  |
| --- | --- |
| Commentaire, ajouter contour | ·         The resource name prefix is **module.**  ·         The suffix is the value of the attribute name and addr  ·         The failover rule is static and predefined, and is named module\_failure |

 

For a description of checkers, refer to section 13.11.3.

To test the module checker, refer to section 4.4.6.

|  |  |
| --- | --- |
| To start the module configuration wizard, refer to section 3.3.  The wizard do not present the module checker. Switch to “Advanced configuration” to configure it. | <!DOCTYPE safe>  <safe>   <service mode="farm" boot="on">    <farm>     <lan name="default"></lan>    </farm>    <vip>     <interface\_list>      <interface check="on">       <virtual\_interface type="vmac\_directed">        <virtual\_addr addr="10.1.0.127" where="alias" check="**on**"/>       </virtual\_interface>      </interface>     </interface\_list>        <loadbalancing\_list>      <group name="FarmProto">       <rule port="9010" proto="tcp" filter="on\_port"/>      </group>     </loadbalancing\_list>    </vip>      <user></user>       <check>     <module name="mirror">       <to addr="10.0.0.129" port="9010"/>     </module>    </check>      </service>  </safe>  For details on XML configuration of <module>, see section 13.17. |

 

|  |  |
| --- | --- |
| Commentaire, ajouter contour | Note that the module dependency can be used when you deploy farm and mirror modules on the same SafeKit cluster or when you deploy farm and mirror modules on two different clusters. In this case, the password set to initialize the web service must be identical on both SafeKit clusters. |

### 15.9.2      Example with leader.safe and follower.safe

The two demonstration modules leader.safe and follower.safe delivered with SafeKit allow you to configure one or more follower
modules whose startup depends on the startup of the main mirror module, named
leader.

For example, the main services of an
application with replicated directories can be configured in the leader module,
and some ancillary services of this application can be started in a follower
module if you consider that its failure should only trigger its own restart;
The other follower modules and the leader module are not impacted, which
ensures service continuity for these modules.

The leader module is configured for a
mirror architecture and includes the start and stop of the follower modules.

Each follower module is configured for a
light architecture with module scripts and error detectors. The follower
modules depend on the leader failover with the following module checker.

**follower/conf/****userconfig.xml** - see section 13

<check>

  <module name="leader"/>

</check>

This is a shortcut for:

<module
name="leader">

 <to
addr="127.0.0.1" port="9010"/>

</module>

For details on XML configuration of <module>, see section 13.17.

|  |  |
| --- | --- |
| Commentaire important contour | If you change the listening port for the SafeKit web service (as described in section 10.9), replace the short configuration with the full one and change the port value. |

## 15.10      Interface checker example

Below is the example of an interface
checker configuration automatically generated when <interface check="on"> is set. For details, refer to section 13.6.

In the userconfig.xml of the
mirror module for instance, the virtual IP address is defined as follows:

<vip>

 
<interface\_list>

    
<interface **check="on"**>

        
<real\_interface>

          
<virtual\_addr addr="10.0.0.129" where="one\_side\_alias"
check="on"/>

        
</real\_interface>

    
</interface>

 
</interface\_list>

</vip>

When configuring the module, SafeKit
generates the corresponding configuration for the interface
checker. For the example, the automatically generated configuration is:

<check>

  <intf
when="pre" ident="10.0.0.0">

    <to
local\_addr="10.0.0.107"/>

  </intf>

</check>

Where the value of ident is the network
corresponding to the virtual IP address; the value of local\_addr is the first
IP address of the network corresponding to the virtual address.

The checker checks that the Ethernet cable
is connected on this interface. If the cable is disconnected, the checker set
the associated resource intf.10.0.0.0 to down.  The static and predefined failover rule, named interface\_failure, executes a wait on the module when this resource goes down.

|  |  |
| --- | --- |
| Commentaire, ajouter contour | ·         The resource name prefix is **intf.**  ·         The suffix is the value of the attribute ident  ·         The failover rule is static and predefined, and is named interface\_failure |

 

For configuration details of interface
checker, see section 13.14.

For a description of checkers, refer to section 13.11.3.

To test the interface checker, refer to section 4.4.4.

## 15.11      IP checker example

Below is the example of an IP checker
configuration automatically generated when <virtual\_addr … check="on"> is set. For details, refer to section 13.6.

In the userconfig.xml of the
mirror module for instance, the virtual IP address is defined as follows:

<vip>

 
<interface\_list>

    
<interface check="on">

        
<real\_interface>

          
<virtual\_addr addr="10.0.0.129" where="one\_side\_alias" **check="on"**/>

        
</real\_interface>

    
</interface>

 
</interface\_list>

</vip>

When configuring the module, SafeKit
generates the corresponding configuration for the IP checker. For the example,
the automatically generated configuration is:

<check>

  <ip
ident="10.0.0.129" when="prim">

   <to
addr="10.0.0.129"/>

  </ip>

</check>

Where the value of ident and addr are
the the virtual IP address; the value of when is prim for a
mirror module, and both for a farm module.

The IP checker checks that the IP address is configured locally.
If the IP address is not configured, the checker set the associated resource ip.10.0.0.129 to down.  The static and predefined failover rule, named ip\_failure,
executes a stopstart on the module when this resource goes down.

|  |  |
| --- | --- |
| Commentaire, ajouter contour | ·         The resource name prefix is **ip.**  ·         The suffix is the value of the attribute ident  ·         The failover rule is static and predefined, and is named ip\_failure |

 

For configuration details of IP checker,
see section 13.15.

For a description of checkers, refer to section 13.11.3.

## 15.12      Virtual hostname example with vhost.safe

The demonstration module vhost.safe
shows how to set a virtual hostname in a mirror module. This feature is also
available in a farm module.

|  |  |
| --- | --- |
| Commentaire, ajouter contour | The following description is for Windows. For Linux, please refer to vhost.safe delivered with the Linux package that includes Linux configuration and scripts. |

 

In Windows, the vhost.safe delivered
since SafeKit 8.2.4 has been enhanced to allow testing the setup of the virtual
hostname for a service. It relies on an HTTP service called testhostname that is created/deleted during the module
configuration/deconfiguration. This service is started/stopped by the module
scripts and listens on port 9999. The http://localhost:9999/hostname endpoint returns the value of the hostname as seen by the testhostname service, which is the virtual hostname when
the module is primary.

### 15.12.1  Module configuration with a virtual hostname

In the following example, one <macro> is configured and its value is used to define the virtual hostname.

|  |  |
| --- | --- |
| To start the module configuration wizard, refer to section 3.3.  The wizard do not present the vhost. Switch to “Advanced configuration” to edit it. | <!DOCTYPE safe>  <safe>  <macro name="virtualname" value="**virtualsrv**"/>     <service mode="mirror" boot="on">   <heart>    <heartbeat name="default">    </heartbeat>   </heart>   <vip>    <interface\_list>     <interface check="**on**">      <real\_interface>       <virtual\_addr addr="10.1.0.126" where="one\_side\_alias" check="on"/>      </real\_interface>     </interface>    </interface\_list>   </vip>   <rfs>    <replicated dir="e:\repdir"/>   </rfs>   <user></user>    <vhost>     <virtualhostname name="%virtualname%" envfile="vhostenv.cmd"/>    </vhost>  </service>  </safe>  For details on XML configuration of <vhost>, see section 13.9. |

 

### 15.12.2  Module scripts with a virtual hostname

In addition to the module configuration,
special commands must be executed in the module scripts.

For details on script logging (with echo and safekit printe commands), refer to section 14.3.

#### 15.12.2.1                      start\_prim script

The script runs commands to set the virtual
hostname in the script environment, as well as in the Windows service
environment.

|  |  |
| --- | --- |
| SafeKit web console image Edit start_prim script of a mirror module, using module configuration wizard | @echo off  echo "Running **start\_prim** %\*"     rem Set virtual hostname  CALL "%SAFEUSERBIN%\vhostenv.cmd"     rem Next commands use the virtual hostname  FOR /F %%x IN ('hostname') DO SET servername=%%x  echo "hostname is "%servername%     "%SAFE%\private\bin\vhostservice" testhostname     set res=0     net start testhostname     set res=%errorlevel%  if %res% == 0 goto end     :stop  "%SAFE%\safekit" printe "start\_prim failed"     rem uncomment to stop the module when critical  rem "%SAFE%\safekit" stop -i "start\_prim"     :end  For safekit command description, refer to section 9. |

#### 15.12.2.2                      stop\_prim script

The script runs commands to reset the virtual
hostname in the script environment, as well as in the Windows service
environment.

|  |  |
| --- | --- |
| SafeKit web console image Edit stop_prim script of a mirror module, using module configuration wizard | @echo off  echo "Running **stop\_prim** %\*"     rem Reset virtual hostname  CALL "%SAFEUSERBIN%\vhostenv.cmd"     rem Next commands use the real hostname  FOR /F %%x IN ('hostname') DO SET servername=%%x  echo "hostname is "%servername%     set res=0     rem default: no action on forcestop  if "%1" == "force" goto end     net stop testhostname  set res=%errorlevel%     rem If necessary, wait for the stop of the services  rem "%SAFEBIN%\sleep" 10     if %res% == 0 goto end     "%SAFE%\safekit" printe "stop\_prim failed"     :end     "%SAFE%\private\bin\vhostservice" testhostname  For safekit command description, refer to section 9. |