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

# 14.          Scripts for an application module configuration

![*](safekituserguideen_fichiers/image001.png)      
Section 14.1 “List of scripts”

![*](safekituserguideen_fichiers/image001.png)      
Section 14.2 “Variables and arguments passed to scripts”

![*](safekituserguideen_fichiers/image001.png)      
Section 14.3 “Scripts output”

![*](safekituserguideen_fichiers/image001.png)      
Section 14.4 “Scripts execution automaton”

![*](safekituserguideen_fichiers/image001.png)      
Section 14.5 “SafeKit special commands for scripts”

 

|  |  |
| --- | --- |
| Sous-titres contour | Examples of scripts are given in section 15. |

To enable scripts call, <user> tag must be defined in userconfig.xml as described in section 13.8.

Scripts must executables:

·        
in Windows, an executable with the extension and
type: .cmd, .vbs, .ps1,.bat or .exe

·        
in Linux, any type of executable

Each time you update scripts, you must
apply the module configuration onto the servers (with the SafeKit console or
command).

|  |  |
| --- | --- |
| Commentaire, ajouter contour | During the configuration phase, scripts are copied from SAFE/modules/*AM*/bin in the execution environment directory SAFE/private/modules/*AM*/bin (=SAFEUSERBIN, do not touch scripts at this place) where *AM* is the module name. |

## 14.1          List of scripts

Below the list of scripts that can be
defined by the user. The essential scripts start/stop are those that start and
stop the application within the module.

### 14.1.1      Start/stop scripts

For a detailed description of when these
scripts are invoked, refer to the script execution automaton presented in section 14.4.

|  |  |
| --- | --- |
| prestart | prestart is called when the module starts (via the SafeKit console or the command safekit start -m *AM*). This script must be present and include calls to the stop\_xx scripts to stop the application before setting up the module’s resources (virtual IP, replication, etc.). |
| poststop | poststop is called when the module is stopped (via the SafeKit console, the command safekit stop -m *AM*, or a shutdown triggered by a checker). This script is optional. |
| start\_prim  stop\_prim | **Mirror module only**  start\_prim is called when the module transitions to the PRIM/ALONE(Ready) states. It must include the startup of the application services.  stop\_prim is called when the module leaves the PRIM/ALONE(Ready) states. It must handle the shutdown of the application services.  The script execution automaton ensures that the application, as defined in these scripts, runs exclusively on the primary node of the mirror module. |
| start\_both  stop\_both | **Typically for a farm module**  start\_both is called when the module transitions to the UP(Ready) state. It must include the startup of the application services.  stop\_both is called when the module leaves the UP(Ready)state. It must handle the shutdown of the application services.  The script execution automaton ensures that the application defined in these scripts runs on all nodes of the farm module.  In the exceptional case where these scripts are present in a mirror module, they are called during transitions to or from the PRIM/ALONE/SECOND(Ready)states. The script execution automaton ensures that the application, as defined in these scripts, runs on both the primary and secondary nodes of the mirror module. |
| start\_second  stop\_second | **Exceptionally for a mirror module**  start\_second is called when the module transitions to the SECOND(Ready)state.  stop\_second is called when the module leaves the SECOND(Ready)state.  These scripts may include actions to perform or undo on a secondary node. |
| start\_sec  stop\_sec | **Exceptionally for a mirror module**  start\_sec is called when the module transitions to the SECOND/ALONE(Ready) states.  stop\_sec is called when the module leaves the SECOND/ALONE (Ready) states.  These scripts may include actions to perform or undo on a secondary node, or on a primary node without a secondary. |
| transition | This script is triggered during major state transitions, as described in section 14.4 |
| update | update is called during the dynamic reconfiguration of the cluster or module, while the module is running and in a stable state.   |  |  | | --- | --- | | Sous-titres contour | For an example, refer to section 15.2.3.2.3. | |

 

|  |  |
| --- | --- |
| Commentaire important contour | Stop scripts are called twice:  ·         First call: for a graceful shutdown (without the force parameter as the first argument)  ·         Second call: if needed, for a forced shutdown (with the force parameter as the first argument) |

### 14.1.2      Other scripts

|  |  |
| --- | --- |
| config | config is called during the initial steps of module configuration (via the SafeKit console or the command safekit config -m *AM*). This script can be used to execute application-specific configuration commands. |
| postconfig | postconfig is called during the final steps of module configuration (via the SafeKit console or the command safekit config -m *AM*). Unlike the moment when config is called, postconfig has access to the final content of the safeconf.xml file, located in SAFEUSERCONF. This file contains the complete XML configuration of the module, after macro instantiation. |
| deconfig | deconfig is called during the module deconfiguration (via the SafeKit console or the command safekit deconfig -m *AM*). Module deconfiguration is also automatically performed during module uninstallation. This script must undo the actions performed in the config script. |
| confcheck | confcheck is called when executing the safekit confcheck -m *AM* command on the application module. You can add in this script some tests for checking changes on the application configuration files. |
| state | state is called when executing the safekit state -v -m *AM* command on the application module. You can display a special state of the application. |
| level | level is called when executing the safekit level -m *AM* command on the application module. You can display the application version. |

## 14.2          Variables and arguments passed to scripts

All scripts are called with 3 parameters:

·        
the current state (STOP,WAIT,ALONE,PRIM,SECOND,UP),

·        
the next state (STOP,WAIT,ALONE,PRIM,SECOND,UP)

·        
the action (start, stop, stopstart
or stopwait).

|  |  |
| --- | --- |
| Commentaire important contour | The stopwait argument is passed during the execution of the wait action triggered by a checker. |

The stop scripts are called twice:

·        
a first time for a graceful shutdown of the
application

·        
a second time with a force parameter for a
forced shutdown (with force as first argument)

The environment variables that can be used
inside scripts are:

·        
SAFE,
SAFEMODULE, SAFEBIN, SAFEUSERBIN, SAFEUSERCONF, SAFEVAR, SAFEUSERVAR (for
details, see section 10.1)

|  |  |
| --- | --- |
| Commentaire important contour | The definition of SAFEMODULE, which contains the name of the module, allows omitting the -m *AM* option with the safekit command if it is to apply to the SAFEMODULE. |

·        
all variables defined in <user> tag of userconfig.xml (see section 13.8).

 

|  |  |
| --- | --- |
| Sous-titres contour | For an example with environment variables defined in <user> tag, refer to section 15.3. |

## 14.3          Scripts output

### 14.3.1      Output into script log

By default (logging="userlog" in <user> tag
of userconfig.xml),
the stdout and stderr of the script are
redirected into the fileSAFEVAR/modules/*AM*/userlog\_<year>\_<month>\_<day>T<time>\_<script
name>.ulog where:

·        
SAFEVAR=C:\safekit\var in Windows and /var/safekit in Linux

·        
*AM* is the module name

·        
<year>\_<month>\_<day>T<time>
are date and time of execution of the script

·        
<script
name> is the script name

To insert a message into the
script log, add the following command into the script:

echo
"message"

or in PowerShell:

Write-Host
"message"

### 14.3.2      Output into module log

To insert messages
with level E or I into the *AM* module log, add the following
command into the script:

·        
in Windows

"%SAFE%/safekit"
printe "message"

"%SAFE%/safekit"
printi "message"

·        
in Linux

"$SAFE/safekit"
printe "message"

"$SAFE/safekit"
printi "message"

Level E
messages are visible in the non-verbose log; level I messages are found in the
verbose log

|  |  |
| --- | --- |
| Commentaire, ajouter contour | In the execution environment of the *AM* script, the -m *AM* option is unnecessary for the safekit command. |

## 14.4          Scripts execution automaton

Most of the time, stop scripts are called
twice (without the force parameter and then with the force parameter). In
that case the script name is written in italic.

|  |  |
| --- | --- |
| Sous-titres contour | For instance, first transition from STOP to WAIT calls the script transition STOP WAIT start is called. |

![Module scripts execution automaton](safekituserguideen_fichiers/image403.png)

 

|  |  |
| --- | --- |
| Commentaire, ajouter contour | Since SafeKit 8.2.4, when stopping the module, the stop\_xxx scripts with the force argument can be executed a second time before the poststop call. |

## 14.5          SafeKit special commands for scripts

Special commands are installed under SAFE/private/bin. Special commands can be called directly in module scripts with %SAFEBIN%\specialcommand or $SAFEBIN/specialcommand. Outside module scripts, use safekit -r command.

 

|  |  |
| --- | --- |
| safekit -r   *<special command>*   [*<args>*] | *<special command> <args>* executed within the SafeKit environment. When the command name is not an absolute path, the command is searched in SAFEBIN=SAFE/private/bin directory. |

### 14.5.1      Commands for Windows

#### 14.5.1.1  sleep, exitcode, sync commands

On Windows, you can use the following basic
commands:

·        
%SAFEBIN%\sleep.exe
<timeout value in seconds>

To be
used inside stop scripts because net stop service is not synchronous

·        
%SAFEBIN%\exitcode.exe
<exit value>

To return
an error value when the script exits

·        
%SAFEBIN%\sync.exe
\\.\<drive letter:>

To sync file
system cache of a disk

#### 14.5.1.2  namealias command

%SAFEBIN%/namealias [-n | -s ] <*alias name*>

-n to add a new NetBIOS
name (se

t into start\_prim)
or -s to suppress the NetBIOS name (set into stop\_prim)

You can also use the SafeKit command netnames
(or the windows command
nbtstat) to list NetBIOS information.

### 14.5.2      Commands for Linux

#### 14.5.2.1  Managing the crontab

|  |  |
| --- | --- |
| $SAFEBIN/gencron   [del | add]   <*user name*>   [all |<*command name*>]   -c "<*comment*>" | ·         del to disable the entries in stop\_prim (by inserting comments)  ·         add to enable the entries in start\_prim (by removing comments)  ·         <*user name*> user name in the crontab  ·         all to apply on all entries  ·         <*command name*> to apply on the name of the command  ·         <*comment*> header of the comment that will be inserted |

The following example applies to the
crontab entry: 

5
0 \* \* \* $HOME/bin/daily.job >> $HOME/tmp/out 2>&1

For a mirror module, to manage this entry
on the primary, insert:

·        
Its activation into start\_prim

$SAFEBIN/gencron
add admin daily.job -c "SafeKit configuration for $SAFEMODULE"

·        
Its deactivation into stop\_prim

$SAFEBIN/gencron
del admin daily.job -c "SafeKit configuration for $SAFEMODULE"

#### 14.5.2.2  Bounding command

|  |  |
| --- | --- |
| $SAFEBIN/boundcmd <*timeout value*> <*command path*> [<*args*>] | ·         <*timeout value*> maximum time allocated to execute the command  ·         <*command path*> path to the command to execute  ·         <*args*> optional arguments to the command |

 

boundcmd returns the exit code of the command when the command terminates
before the timeout; otherwise, it exits with the value 2.

For example, to flush data on disk with a
timeout of 30 seconds, run:

$SAFEBIN/boundcmd
30 /bin/sync 1>/dev/null 2>&1

### 14.5.3       Commands for Windows and Linux

|  |  |  |  |
| --- | --- | --- | --- |
| safekit -r processtree list | kill … | List running processes as a tree (except for all) and optional kill  ·         safekit -r processtree list all  List all running processes.  ·         safekit -r processtree list <*process command name*>  List all running processes with the specified command name.  ·         safekit -r processtree kill <process command name>  List and kill all running processes with the specified command name.  ·         safekit -r processtree list | kill <*process command name*>| all <*regular expression on the full command - path and arguments*>  List (and kill) all running process with the specified command name and arguments.   |  |  | | --- | --- | | Commentaire, ajouter contour | For regular expression syntax:  ·         in Windows, see class CatlRegExp  ·         In Linux, see man regex |   ·         Windows examples  safekit -r processtree kill notepad.exe ".\*myfile.\*"     safekit -r processtree list all "mirror"  ·         Linux examples  safekit -r processtree kill vi ".\*myfile.\*"     safekit -r processtree list all "mirror" |
| safekit incloop  -m *AM* -i <*handler name*> | The module has  a maxloop counter, the number of restart, stopstart and wait of the module on error detection. The module is stopped when this counter reaches the maxloop value over the loop\_interval period.  When running special handlers, the maxloop counter is not incremented. To increment it, use the command:  safekit incloop -m *AM* -i <handler name>  It increments the maxloop counter for the module *AM* and returns 1 when the limit has been reached.   |  |  | | --- | --- | | Sous-titres contour | For an example, refer to section 15.4.2. | |
| safekit resetloop  -m *AM* [-i <*handler name*>] | Reset the maxloop counter to the value 0 |
| safekit checkloop -m *AM* | For checking the maxloop counter for the module *AM*, use the command: safekit checkloop -m *AM*  •      It returns 0 when the maxloop counter is not reached or the last increment occurred outside loop\_interval  •      It returns 1 when the maxloop counter is reached and the last increment occurred during loop\_interval |