====== shaman-scripts ====== ---- ===== NAME ===== shaman-scripts − main resource control scripts used by **shaman** and **shaman-monitor**. ===== SYNOPSIS ===== /usr/share/shaman/notify /usr/share/shaman/enumerate /usr/share/shaman/schedule /usr/share/shaman/relocate /usr/share/shaman/start /usr/share/shaman/describe /usr/share/shaman/leave ===== DESCRIPTION ===== **shaman-scripts** is a group of highly customizable scripts used by the **shaman** command-line tool and **shaman-monitor** daemon for managing and monitoring containers, virtual machines, iSCSI targets and other clustering resources on R-Virtualization nodes. Depending on a purpose and resource type, the scripts can call a series of other scripts for handling resources. Resource names usually have the following prefixes: **ct-** prefix is used in container resource names, **vm-** prefix is used for virtual machine resources, and **iscsi-** prefix is used for iSCSI targets. The default scripts are stored locally in ///usr/share/shaman//. Custom user scripts can be stored locally in ///usr/share/shaman// or on shared storage at ///.shaman-scripts//. Custom script names should conform to the pattern **XX-purpose** where **XX** is the order number which allows creating multiple custom scripts for the same purpose. Shared storage custom scripts run first followed by the local custom scripts in numerical order, as long as there are resources to be relocated from the node. If all custom scripts fail, the default script for that purpose is run. ===== PURPOSE ===== The following default scripts are used by the **shaman** command-line tool and **shaman-monitor** daemon: **\\ notify** Called by **shaman-monitor** running on the master node. The script defines custom actions to be executed during each of the cluster events. The current cluster event can be obtained from the **EVENT** environment variable (see the **HANDLED EVENTS** section below for details), while the IP address, node identifier, and resource name can be obtained from the **IP_ADDRESS**, **SRC_NODE_ID** and **RESOURCE** environment variables, respectively. **enumerate** Prints to stdout the list of names for existing resources that are to be registered in the cluster on executing the **shaman join** command. See **shaman**(8) for details. **schedule** Сalled by **shaman-monitor** on the master node when the **NODE_CRASHED** event is processed. The script is used to decide where to relocate resources from the failed node. If no nodes support the role required by the resource, said resource goes into the broken state. Script input is provided by the environment variables **NODE_LIST_FILE** (the list of nodes that resources can be relocated to), **RESOURCES_LIST_FILE** (the list of resources waiting for relocation), and **SRC_NODE_ID** (the crashed node ID).\\ Prints results to the file descriptor provided by the environment variable **OUTPUT_FD** in the following format: //node_ip node_id resource_name//. All fields in the output are separated by space, and each line ends with a new line character. The master node reads the printed strings and moves the specified resource to the pools of appropriate nodes. If a schedule script exits with a non-zero output, relocation suggestions in this output are discarded. If you have a **pdrs** package installed and the **shaman** global config contains the **drs** resource relocation mode in the RESOURCE_RELOCATION_MODE list, the **pdrs_schedule** script will be used instead of the default **schedule** script. **relocate** Takes control over the resources (specified in the **RESOURCE** environment variable) that were relocated to the **Pool** of the specified node. The script is used by **shaman-monitor** and called only if the resource exists in the **Pool** (i.e. the resource is waiting for relocation). The checkout is performed every **POOL_CHECK_TIMEOUT** seconds; see **shaman.conf**(5) for details. **start** Is executed by **shaman-monitor** when a node recovers from a crash and becomes available again. By default, the script starts the resource (specified in the **RESOURCE** environment variable) if it was running before the node crash. **describe** Is used by the **shaman stat** and **shaman top** commands to retrieve the description of specific resources. Descriptions are printed in XML format to the screen. For example: <**descr type**=//"$TYPE"//> |||<**id width**=//"20"//>//$CTID//<**/id**> | |||<**pwrr width**=//"10"//>//$STATE//<**/pwrr**>| <**/descr**> In this example, **shaman stat** and **shaman top** print the **id** and **pwrr** fields and fill them with the //$CTID// and //$STATE// values, respectively, for the specified resource type. The **pwrr** field shows how shaman will handle the resource state if relocation occurs - whether it will turn on the resource or not. The **type** attribute is used to differentiate your resource types and print them as grouped records. If you omit this attribute, all resources with the specified description will be marked as **Unknown**. The **width** attribute is used to specify the column width of the field, in pixels. If you omit this attribute, the default value of 10 pixels is used. You can specify your own descriptions of control resources or add custom fields to existing ones using the output format described above. **leave** Executed by the **shaman leave** command when a node leaves cluster. ===== HANDLED EVENTS ===== **NODE_CRASHED** Node with **IP_ADDRESS** has crashed. **RESOURCE_RELOCATED** **RESOURCE** was successfully relocated to the node with **IP_ADDRESS**. **RELOCATION_FAILED** Failed to relocate **RESOURCE** to the node with **IP_ADDRESS**. ===== ENVIRONMENT VARIABLES ===== The following environment variables are used by **shaman-scripts**: **\\ EVENT**=//name// The //name// of the processed cluster event. See the **HANDLED EVENTS** section for details. **IP_ADDRESS**=//ip// IP address assigned to the node. **NODE_LIST_FILE**=//path// Path to the file containing the list of active nodes in the cluster. This file contains the list of **ip_address node_id node_roles** tuples for all active nodes, where **node_id** is the internal identifier used by **shaman** and **shaman-monitor**, **node-roles** is the list of roles separated with commas and without spaces. The fields in pairs are separated by spaces, and each line ends with a new line character. **RESOURCE**=//name// Contains the internal representation of a controlled resource (including the resource type and name). **RESOURCE_PATH**=//path// Full path to the directory for storing the resource. **RESOURCE_LIST_FILE**=//path// This file contains the following records, one for each resource from the broken node: nameprioritypath. The fields are separated by spaces, and each line ends with a new line character. **SRC_NODE_ID**=//node_id// Node id of node whose resources are to be relocated. **OUTPUT_FD**=//number// File descriptor of the output file. **BROKEN**= The value 1 indicates that the resource specified in the RESOURCE environment variable is broken and requires special treatment. ===== FILES ===== ///usr/share/shaman/notify\\ /usr/share/shaman/enumerate\\ /usr/share/shaman/schedule\\ /usr/share/shaman/relocate\\ /usr/share/shaman/start\\ /usr/share/shaman/describe\\ /usr/share/shaman/leave// The default locations of the resource controlling scripts. ===== SEE ALSO ===== **[[domestic:rosplatforma:man:shaman]]**(8), **[[domestic:rosplatforma:man:shaman-monitor]]**(8), **[[domestic:rosplatforma:man:shaman.conf]]**(5), ===== COPYRIGHT ===== Copyright (c) 2013-2017 R-Platforma LLC, All rights reserved. Copyright (c) 2017-2019 R-Platforma LLC, All rights reserved. ----