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

# 13.          Userconfig.xml for an application module configuration

![*](safekituserguideen_fichiers/image001.png)      
Section 13.1 “Time-based attributes”

![*](safekituserguideen_fichiers/image001.png)      
Section 13.2 “Macros - <macro>”

![*](safekituserguideen_fichiers/image001.png)      
Section 13.3 “Farm or mirror module - <service>”

![*](safekituserguideen_fichiers/image001.png)      
Section 13.4 “Heartbeats - <heart>, <heartbeat >”

![*](safekituserguideen_fichiers/image001.png)      
Section 13.5 “Farm topology - <farm>, <lan>”

![*](safekituserguideen_fichiers/image001.png)      
Section 13.6 “Virtual IP address - <vip>”

![*](safekituserguideen_fichiers/image001.png)      
Section 13.7 “File replication - <rfs>, <replicated>”

![*](safekituserguideen_fichiers/image001.png)      
Section 13.8 “Module scripts - <user>, <var>”

![*](safekituserguideen_fichiers/image001.png)      
Section 13.9 “Virtual hostname - <vhost>, <virtualhostname>”

![*](safekituserguideen_fichiers/image001.png)      
Section 13.10 “Process or service monitoring - <errd>, <proc>”

![*](safekituserguideen_fichiers/image001.png)      
Section 13.11 “Checkers - <check>”

![*](safekituserguideen_fichiers/image001.png)      
Section 13.12 “TCP checker - <tcp>”

![*](safekituserguideen_fichiers/image001.png)      
Section 13.13 “Ping checker - <ping>”

![*](safekituserguideen_fichiers/image001.png)      
Section 13.14 “Interface checker - <intf>”

![*](safekituserguideen_fichiers/image001.png)      
Section 13.15  “IP checker - <ip>”

![*](safekituserguideen_fichiers/image001.png)      
Section 13.16 “Custom checker - <custom>”

![*](safekituserguideen_fichiers/image001.png)      
Section 13.17 “Module checker - <module>”

![*](safekituserguideen_fichiers/image001.png)      
Section 13.18 “Splitbrain checker - <splitbrain>”

![*](safekituserguideen_fichiers/image001.png)      
Section 13.19 “Failover machine - <failover>”

 

Each time you modify userconfig.xml, the configuration must be applied to all the nodes of the cluster
onto which the application module is installed, to become the active
configuration.

To apply the new configuration modified on node1, on
all cluster nodes, follow the procedure below (replace node1, node2 by the
nodes name and *AM* by the module name).

·        
the web console, connected to node1, by
navigating to ![](safekituserguideen_fichiers/image349.png)“Configuration/Modules
configuration/  
![](safekituserguideen_fichiers/image349.png)Configure
the module/”

·        
or the web console, connected to node1,  by
directly entering the URI /console/en/configuration/modules/*AM*/config/

·        
or the command safekit config -H "node1,node2" -E *AM* executed
on node1

 

Example of userconfig.xml:

<safe>

  <!--
Insert below <macro> <service> tags -->

</safe>

|  |  |
| --- | --- |
| Commentaire important contour | With the web console, the module must be stopped before applying the configuration.  With command line, it is possible to apply a new configuration while the module is running, but only in ALONE (Ready) or WAIT (NotReady) states. This feature is called *dynamic configuration*. Only a restricted subset of parameters could be changed. If the new configuration cannot be deployed, an error message is displayed.  The attributes that can be dynamically modified are reported hereafter. |

 

## 13.1          Time-based attributes

Before SafeKit 8.2.5, configuration
attributes representing a duration (such as timeout, interval, pulse…)
were expressed as numeric values without explicitly specifying the time unit.

Starting with SafeKit version 8.2.5, most
of time- based attributes now explicitly support time units in their values.
This enhancement makes the settings more intuitive and eliminates ambiguity.
The previous syntax without explicit time units remains fully supported in
SafeKit 8.2.5. Existing configurations will continue to function without any
changes.

|  |  |
| --- | --- |
| Commentaire important contour | Time- based attributes retain a default value and time unit, which affects how user-provided values are interpreted (see section 13.1.2). |

In the rest of the document, default values
for attributes that support a time unit are expressed with the corresponding
unit. For versions prior to SafeKit 8.2.5, simply remove the unit to obtain the
default value.

### 13.1.1      Time-based attribute example

For instance, prior to SafeKit version
8.2.5, the loop\_interval attribute, representing a time interval in hours to which maxloop
applies, was expressed as:

<service
mode="mirror" maxloop="3" loop\_interval="**24**">

…

</service>

Starting with SafeKit 8.2.5, the syntax has
been enhanced to explicitly include the time unit as follow:

<service
mode="mirror" maxloop="3" loop\_interval="**24h**">

…

</service>

This new syntax improves readability and
removes any ambiguity regarding the unit of time.

### 13.1.2      Time-based attribute syntax

The supported units in SafeKit 8.2.5 for
time-based attributes are:

·        
d for day (e.g. "1d")

·        
h for hour (e.g. "2h")

·        
m for minute (e.g. "3m")

·        
s for second (e.g. "10s")

·        
ms for millisecond (e.g. "700ms")

·        
us for microsecond (e.g. "50us")

 

Time-based attributes retain a default
value and time unit, which affects how user-provided values are interpreted.
For instance, if an attribute has a default value of 10s, its implicit
unit is seconds. If the user specifies a value like 5ms, it will be
converted to seconds (0.005s) and rounded to 0s. In this case, the module configuration will fail with an error
such as:

Error:
invalid value '500ms' for the attribute boot\_delay (expected time unit: 's')

If the value 0 is valid in the module
configuration, assign it without a time unit or using the expected unit.

## 13.2          Macros - <macro>

Use a macro to associate a name with a
value. In the userconfig.xml, the name, enclosed by the % character, is
replaced by the value of the corresponding macro.

|  |  |
| --- | --- |
| Commentaire, ajouter contour | The syntax %identifier% can also be used in userconfig.xml to represent the value of an environment variable named identifier. In case of conflict, it is the macro value that is expanded. |

### 13.2.1      <macro> example

In the example below, %PATH% is
replaced by e:\path.

<macro name="PATH" value="e:\path"/>

<service>

  …

  <rfs>

  
<replicated dir="%PATH%" />

  </rfs>

</service

|  |  |
| --- | --- |
| Sous-titres contour | For an example of macro usage, refer to section 15.3. It presents the configuration via the web console along with the corresponding userconfig.xml. |

### 13.2.2      <macro> syntax

<macro

    
name="*identifier*"

    
value="*value*"

/>

### 13.2.3      <macro> attributes

|  |  |
| --- | --- |
| <macro |  |
| name="*identifier*" | A character string that identifies the macro. |
| value="*value*" | The value that will replace each occurrence of %identifier% in the rest of userconfig.xml. |
| /> |  |

## 13.3          Farm or mirror module - <service>

The <service> tag
is the top-level section defining a module configuration, in particular the
module mode (mirror, farm or light) and whether it starts at boot.

### 13.3.1      <service> example

#### 13.3.1.1  Example for a mirror module

<service
mode="mirror" boot="on" maxloop="3"
loop\_interval="24h">

  <!--
Insert below <hearbeat> <rfs> <vip> <user> <vhost>
<errd> <check> <failover> tags -->

</service>

|  |  |
| --- | --- |
| Sous-titres contour | For a full example of a mirror module, refer to section 15.1. It presents the configuration via the web console along with the corresponding userconfig.xml. |

#### 13.3.1.2  Example for a farm module

<service
mode="farm" boot="on" maxloop="3"
loop\_interval="24h">

  <!--
Insert below <farm> <vip> <user> <vhost> <errd> <check>
<failover> tags -->

</service>

|  |  |
| --- | --- |
| Sous-titres contour | For a full example of a farm module, refer to section 15.2. It presents the configuration via the web console along with the corresponding userconfig.xml. |

#### 13.3.1.3  Example for a light module

<service
mode="light" boot="on" maxloop="3"
loop\_interval="24">

  <!--
Insert below <user> <vhost> <errd> <check>
<failover> tags -->

</service>

|  |  |
| --- | --- |
| Sous-titres contour | For an example of a light module, refer to the follower module described in section 15.9.2. |

### 13.3.2      <service> syntax

<service
mode="mirror"|"farm"|"light"

 
[boot="off"|"on"|"auto"|"ignore"]  

 
[boot\_delay="0s"]         

  [failover="on"|"off"]

 
[defaultprim="alone"|"*server\_name*"|"lastprim"]

  [maxloop="3"]
[loop\_interval="24h"]

  [automatic\_reboot="off"|"on"]>

</service>

|  |  |
| --- | --- |
| Commentaire, ajouter contour | Only boot, boot\_delay, maxloop, loop\_interval and automatic\_reboot attributes can be changed with a dynamic configuration. |

### 13.3.3      <service> attributes

|  |  |
| --- | --- |
| <service | Top level section of userconfig.xml |
| mode=  "mirror"|  "farm"|  "light" | ·         mode="mirror" for mirror module (section 1.2)  The synchronization protocol between the 2 servers is defined in section 13.4.   |  |  | | --- | --- | | Sous-titres contour | For a full example of a mirror module, refer to section 15.1. |   ·         mode="farm" for farm module (see section 1.3)  The synchronization protocol between the 2 servers is defined in section 13.5.   |  |  | | --- | --- | | Sous-titres contour | For a full example of a farm module, refer to section 15.2. |   ·         mode="light" for light (see section 1.2.9)  It is a module set to the minimum needed for one server with error detection and local restart only (no failover). |
| [boot=  "on"|  "off"|  "auto"|  "ignore"] | ·         boot="on"  the module is automatically started at boot time.  ·         boot="off"  the module is not started at boot time.  ·         boot="auto"  the module is automatically started at boot time if it was started before the reboot.  ·         boot="ignore"  Before SafeKit 7.5, the configuration to start the module at boot was done with the command safekit boot -m *AM* on | off (which had to be executed on each node). If you prefer to continue using this command, remove the boot attribute or set it to ignore (the default). The module will not be started at boot time unless the safekit boot -m *AM* on command is executed.  The state of the boot configuration is visible in the usersetting.boot resource. To check the state of resources, see section 7.4.  Default value: ignore |
| [boot\_delay="0s"] | The delay, in seconds, before starting the module at boot.  Default value: 0s (no delay)   |  |  |  | | --- | --- | --- | | Commentaire, ajouter contour | | Time unit supported since SafeKit 8.2.5 (see section 13.1). | | Commentaire, ajouter contour | This attribute’s value can be changed with a dynamic configuration. | | |  |  |  | |
| [failover=  "on"|  "off"] | For mirror module only.  ·         failover="on"  An automatic failover on the secondary server is triggered if the primary fails or stops.  ·         failover="off"  When the primary server fails or stops, the secondary server waits (no automatic failover is triggered). Only the prim command can start the secondary server as primary. See description in section 5.7.  Default value: on |
| [defaultprim=  "alone"|  "*server\_name*"|  "lastprim"] | For mirror module only.  defaultprim specifies which server among two servers is the default primary server for an application module.  This option is useful when a module is ALONE on a server and the module is started on the other server.  ·         defaultprim="alone"  The ALONE module becomes PRIM while the module on the other server becomes SECOND. Value recommended avoiding swap of application after reintegration.  ·         defaultprim="*server\_name*"  When the module is running on two servers, the primary server among the two servers is the one set in defaultprim. This value can be useful for active/active (see section 1.4.2) or N-1 active (see section 1.4.3) architectures.  ·         defaultprim="lastprim"  The restarted module becomes PRIM if it was PRIM before its last stop.  Default value: alone |
| [maxloop="3"] | Number of consecutive error detections before stopping.  This attribute defines the maximum number of actions (restart, stopstart, wait) that can be executed following an error detection issued by <errd> or a <checker>, before locally stopping the module.  The counter is reset at the expiration of the loop\_interval timeout and upon safekit start, restart, swap, stopstart… administrative commands execution.  Note that a safekit command sent by a detector passes the -i identity parameter and increments the counter, whereas administrator issued commands reset it.   |  |  | | --- | --- | | Commentaire, ajouter contour | This attribute’s value can be changed with a dynamic configuration. |   The maxloop is represented by the resource heart.stopstartloop. Its current value corresponds to the date on which the counter was initialized (in the form of a Unix Epoch timestamp); and its assignment date corresponds either to its initialization or to a stopstart, restart. View the resource history to see each increment of the maxloop counter.  Default value: 3 |
| [loop\_interval  ="24h"] | Time interval, in hours, during which maxloop applies.  If set to 0, the maxloop counter becomes inactive.  Default value: 24h (24 hours)   |  |  |  | | --- | --- | --- | | Commentaire, ajouter contour | | Time unit supported since SafeKit 8.2.5 (see section 13.1). | | Commentaire, ajouter contour | This attribute’s value can be changed with a dynamic configuration. | | |  |  |  | |
| [automatic\_reboot  =  "off"|  "on"] | If set to on, stopstart triggers a reboot instead of stopping and restarting the module.  Default value: off   |  |  | | --- | --- | | Commentaire, ajouter contour | This attribute’s value can be changed with a dynamic configuration. | |

## 13.4          Heartbeats - <heart>, <heartbeat >

**For mirror modules only**

Heartbeats must be used only for mirror
architecture. For farm architecture, see section 13.5.

The basic mechanism for synchronizing two
servers and detecting server failures is the heartbeat, which is a monitoring
data flow on a network shared by a pair of servers. Normally, there are as many
heartbeats as there are networks shared by the two servers. In normal
operation, the two servers exchange their states (PRIM, SECOND,
the resource states) through the heartbeat mechanism and synchronizes their
application start and stop procedures.

If all heartbeats are lost, it is
interpreted as if the other server was down, and the local server switches to
the ALONE state. Although not mandatory, it is better to have two heartbeat
channels on two different networks for synchronizing the two servers to avoid
the split-brain case.

The network used by the heartbeat is
defined by the logical name of a network set into the SafeKit cluster
configuration (for details, see section 12).

### 13.4.1      <heart> example

|  |  |
| --- | --- |
| Sous-titres contour | For a full example of in a mirror module, refer to section 15.1. It presents the configuration via the web console along with the corresponding userconfig.xml. |

·        
Basic example to configure heartbeat on the
cluster network named default

<heart>

  
<heartbeat name="default" />

</heart>

·        
Example with 2 heartbeats, one dedicated
replication network configured with ident="flow" on the cluster network named private

<heart>

  
<heartbeat name="default" />

  
<heartbeat name="private" ident="flow"/>

</heart>

### 13.4.2      <heart> syntax

<heart

 
[port="xxxx"] [pulse="700ms"] [timeout="30000ms"]  
  [permanent\_arp="on"]

> 

 <heartbeat

 
[pulse="700ms"] [timeout="30000ms"] name="*network*"
[ident="*name*"]

 >

</hearbeat>

 …

</heart>

|  |  |
| --- | --- |
| Commentaire, ajouter contour | The <heart> tag and full subtree can be changed with a dynamic configuration. |

### 13.4.3      <heart>, <heartbeat > attributes

|  |  |
| --- | --- |
| <heart |  |
| [port="*xx*"] | UDP port on which all the heartbeats are exchanged.  Default: depends on the id of the application module. Returned by the safekit module getports command. |
| [pulse="700ms"] | The delay, in milliseconds, between two heartbeat packets.  Default value: 700ms (700 milliseconds)   |  |  | | --- | --- | | Commentaire, ajouter contour | Time unit supported since SafeKit 8.2.5 (see section 13.1). | |
| [timeout=  "30000ms"] | Timeout value, in milliseconds, for heartbeat loss detection.  Default value: 30000ms (30000 milliseconds)   |  |  | | --- | --- | | Commentaire, ajouter contour | Time unit supported since SafeKit 8.2.5 (see section 13.1). | |
| [permanent\_arp=  "on"|"off"] | Regularly, heart sets a permanent ARP entry for the ip addresses associated with the heartbeats.  On some Linux systems, it may cause heart to freeze. Set this parameter to off in this case and manually set permanent arp for the remote server on boot. On Linux, this can be done by inserting the following line into a script that is executed at boot:  arp -s hostname hw\_addr  Default value: on |
| <heartbeat | Definition of one heartbeat. There are as many <heartbeat> tags as there are networks used to probe servers’ mutual connectivity. At least one heartbeat must be defined. |
| name="*network*" | Network named used by the heartbeat. *network* must be the name of a  network set into the SafeKit cluster configuration (for details, see section 12).  This attribute is mandatory in new config syntax (since SafeKit 7.2). |
| [ident="*name*"] | Set how the heartbeat will be labelled in the web console and in internal resources. The associated resource name heartbeat.name.  If no ident attribute is present the value of the name attribute will be used.   |  |  | | --- | --- | | Commentaire important contour | ident="flow" is a reserved name associated with a heartbeat declared for a replication flow. If you set a heartbeat with ident="flow", automatically the replication flow will be set on the same network.  If you set ident="flow" without <rfs> configuration, the module start blocks in WAIT state. | |
| [pulse="700ms"] | Redefines the delay in milliseconds between two heartbeat packets. Default value is the same as the one defined in <heart> tag.  Default value: 700ms (700 milliseconds)   |  |  | | --- | --- | | Commentaire, ajouter contour | Time unit supported since SafeKit 8.2.5 (see section 13.1). | |
| [timeout=  "30000ms"] | Redefines the timeout value, in milliseconds, for heartbeat loss detection. Default value is the same as the one defined in <heart> tag.  Default value: 30000ms (30000 millisecondes)   |  |  | | --- | --- | | Commentaire, ajouter contour | Time unit supported since SafeKit 8.2.5 (see section 13.1). | |
| [<server addr=  "IP1\_address />] | **Legacy** definition of the server address in the heartbeat.  The <server> tag is a legacy syntax used in previous SafeKit version (before SafeKit 7.2). It’s supported for compatibility reasons but must not be used for new modules.   |  |  | | --- | --- | | Commentaire important contour | In the same userconfig.xml, you must not use the syntax for SafeKit 7.1 and the one for SafeKit 7.2. | |

## 13.5          Farm topology - <farm>, <lan>

**For farm modules only**

The basic mechanism to synchronize a farm
of servers is a group communication protocol which automatically detects the
available members of the farm. Normally, the membership protocol is configured
on all networks connecting the N servers.

The network used by the protocol is defined
by the logical name of a network set into the SafeKit cluster configuration
(for details, see section 12).

### 13.5.1      <farm> example

Basic example to use the cluster network
named default.

<farm>

   <lan
name="default" />

</farm>

|  |  |
| --- | --- |
| Sous-titres contour | For full examples in a farm module, see section 15.2. It presents the configuration via the web console along with the corresponding userconfig.xml. |

 

 

<farm>

   <lan
name="default" />

</farm>

 

 

### 13.5.2      <farm> syntax

<farm
[port="xx"]>

   <lan
name="*network*"></lan>

   …

</farm>

|  |  |
| --- | --- |
| Commentaire, ajouter contour | The <farm> tag and subtree **cannot** be changed with a dynamic configuration. |

### 13.5.3      <farm>, <lan> attributes

|  |  |
| --- | --- |
| <farm | Begin the definition of a farm topology. |
| [port="*xx*"] | UDP port with which the membership protocol is exchanged.  Default: depends on the id of the application module. Returned by safekit module getports command. |
| [pulse="100ms"] | Delay, in milliseconds, between two heartbeat packets emitted by the membership protocol.  Longer pulse makes the membership protocol use less bandwidth but reacts more slowly.  Default value: 100ms (100 milliseconds)   |  |  | | --- | --- | | Commentaire, ajouter contour | Time unit supported since SafeKit 8.2.5 (see section 13.1). | |
| [mlost\_count="20"] | Number of heartbeats not received before electing a new leader node.  Default value: 20 ~ 20 x pulse (2000 milliseconds)   |  |  | | --- | --- | | Commentaire, ajouter contour | If the module’s verbose log contains repeated disconnection messages from vipd, such as:  | vipd | D | Lost contact from peer=171.27.1.60  | vipd | D | Lost contact from node1  it is recommended to increase this value to 80 to improve connection stability. | |
| [slost\_count="10"] | Number of heartbeats not received before declaring a follower node offline.  Default value: 10 ~ 10 x pulse (1000 milliseconds)   |  |  | | --- | --- | | Commentaire, ajouter contour | In case of recurring disconnection messages from vipd reported in the module’s verbose log, consider raising this value to 40. | |
| <lan | Definition of a LAN (i.e., IPv4 broadcast domain, IPv6 link) on which the membership protocol will be transmitted. At least one LAN must be defined. Define one such tag per used LAN. |
| name="*network*" | Define the name of network used. network must be the name of a network set into the SafeKit cluster configuration (see section 12).  This attribute is mandatory in new config syntax (since SafeKit 7.2). |
| [<node name="identity" addr= "IP1\_address**" />]** | **Legacy** address and name of the node on this lan. The node tag is a legacy syntax used in previous SafeKit version (before SafeKit 7.2). It’s supported for compatibility reason but must not be used for new modules.   |  |  | | --- | --- | | Commentaire important contour | In the same userconfig.xml, you must not use the syntax for SafeKit 7.1 and the one for SafeKit 7.2. | |