meta data for this page
  •  

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
domestic:rosplatforma:man:shaman [2023/01/26 08:10] – created mchusdomestic:rosplatforma:man:shaman [2023/01/26 14:34] (current) – mchus
Line 6: Line 6:
 ===== SYNOPSIS  ===== ===== SYNOPSIS  =====
  
-shaman [-c cluster_name] [options...] [**command** [command options]] +  * ''shaman [-c cluster_name] [options...] [**command** [command options]]'' 
- +  * ''shaman [-c cluster_name] **join** [**-r, --ignore-res**]'' 
-shaman [-c cluster_name] **join** [**-r, --ignore-res**] +  * ''shaman [-c cluster_name] **leave** [**-n, --node-ip** //<address>//] [**-N, --node-id** //<ID>//]'' 
- +  * ''shaman [-c cluster_name] **stat** [**-X, --xml**] [**-g, --group**] [**-n, --node-ip** //<address>//] [**-N, --node-id** //<ID>//]'' 
-shaman [-c cluster_name] **leave** [**-n, --node-ip** //<address>//] [**-N, --node-id** //<ID>//] +  * ''shaman [-c cluster_name] **top** [**-g, --group**] [**-n, --node-ip** //<address>//] [**-N, --node-id** //<ID>//]'' 
- +  * ''shaman [-c cluster_name] **get-config** [**-X, --xml**]'' 
-shaman [-c cluster_name] **stat** [**-X, --xml**] [**-g, --group**] [**-n, --node-ip** //<address>//] [**-N, --node-id** //<ID>//] +  * ''shaman [-c cluster_name] **set-config** [//key=val// ...]'' 
- +  * ''shaman **get-config-local**'' 
-shaman [-c cluster_name] **top** [**-g, --group**] [**-n, --node-ip** //<address>//] [**-N, --node-id** //<ID>//] +  * ''shaman [-c cluster_name] **cleanup-broken**'' 
- +  * ''shaman [-c cluster_name] **get-roles** [**-X, --xml**]'' 
-shaman [-c cluster_name] **get-config** [**-X, --xml**] +  * ''shaman [-c cluster_name] **set-roles**'' 
- +  * ''shaman [-c cluster_name] **list-supported-roles**'' 
-shaman [-c cluster_name] **set-config** [//key=val// ...] +  * ''shaman [-c cluster_name] **sync** [**-D, --dry-run**]''
- +
-shaman **get-config-local** +
- +
-shaman [-c cluster_name] **cleanup-broken** +
- +
-shaman [-c cluster_name] **get-roles** [**-X, --xml**] +
- +
-shaman [-c cluster_name] **set-roles** +
- +
-shaman [-c cluster_name] **list-supported-roles** +
- +
-shaman [-c cluster_name] **sync** [**-D, --dry-run**]+
  
 ===== DESCRIPTION  ===== ===== DESCRIPTION  =====
  
-**shaman** is a command-line tool for managing and monitoring clustering resources on R-Virtualization nodes. You can use this tool to enable or disable high availability support for R-Storage clusters, monitor global cluster events, and view the overall cluster statistics.+''shaman'' is a command-line tool for managing and monitoring clustering resources on R-Virtualization nodes. You can use this tool to enable or disable high availability support for R-Storage clusters, monitor global cluster events, and view the overall cluster statistics.
  
 Cluster resources are objects in R-Storage clusters, such as virtual machines and Containers, configured to be managed by the R-Virtualization high availability tool. Cluster resources are objects in R-Storage clusters, such as virtual machines and Containers, configured to be managed by the R-Virtualization high availability tool.
Line 40: Line 28:
 ===== OPTIONS  ===== ===== OPTIONS  =====
  
-These options can be used with any **shaman** command. **\\ +These options can be used with any ''shaman'' command. ''**-c, --cluster** //<name>//''
--c, --cluster** //<name>//+
  
-Set the //name// of the cluster to operate on. If (-c) is omitted, the **shaman** service will operate on the cluster specified in the **shaman.conf**(5) file.+Set the ''//name//'' of the cluster to operate on. If (''-c'') is omitted, the ''shaman'' service will operate on the cluster specified in the **[[domestic:rosplatforma:man:shaman.conf]]**(5) file.
  
-**-v, --verbose** +  * ''-v'', ''--verbose'' - Increase the log verbosity level specified in the **[[domestic:rosplatforma:man:shaman.conf]]**(5) file. 
- +  * ''-q'', ''--quiet'' - Disable printing of messages to the console. 
-Increase the log verbosity level specified in the **shaman.conf**(5) file. +  * ''-V'', ''--version'' - Print the ''shaman'' version. 
- +  * ''-h'', ''--help'' - Display the list of allowed options.
-**-q, --quiet** +
- +
-Disable printing of messages to the console. +
- +
-**-V, --version** +
- +
-Print the **shaman** version. +
- +
-**-h, --help** +
- +
-Display the list of allowed options.+
  
 ===== COMMANDS  ===== ===== COMMANDS  =====
  
-**join** [**-r, --ignore-res**]+  * ''join [-r, --ignore-res]'' - Enable high availability support for the local node. High availability can be enabled for R-Storage clusters only; other shared storage solutions, like NFS, are not supported. The shaman tool automatically gets control over all cluster resources after you enable high availability support. You can use ''-r, --ignore-res'' option to forbid ''shaman'' to take control over cluster resources. Use this option only if you know what you are doing. 
 +  * ''leave [-n, --node-ip //<address>//] [-N, --node-id //<ID>//]'' - Disable high availability support. If an IP address or an internal ID is specified, high availability support is disabled for the corresponding node. You can obtain the IP address and internal ID of a node using the ''stat'' command. 
 +  * ''stat [-X, --xml] [-g, --group] [-n, --node-ip //<address>//] [-N, --node-id //<ID>//]'' - Retrieve cluster statistics once and print it in text or XML format (for the latter, specify the ''-X, --xml'' option). 
 +  * ''top [-g, --group] [-n, --node-ip //<address>//] [-N, --node-id //<ID>//]'' - Show dynamic cluster statistics in real time. 
 +  * ''get-config [-X, --xml]'' - Print the global configuration settings in text or XML format. For more details, see ''[[domestic:rosplatforma:man:shaman.conf]]''(5). 
 +  * ''set-config [//key=val// ...]'' - Set the global configuration settings. See shaman.conf(5) for more details. If no //key=val// pairs are specified in the command line, the configuration parameters are read from standard input. 
 +  * ''get-config-local'' - Print the local configuration settings in text format. For more details, see ''[[domestic:rosplatforma:man:shaman.conf]]''(5). 
 +  * ''get-roles [-X, --xml]'' - Show the list of roles set for the local node. 
 +  * ''set-roles <//roles//>'' - Set the list of roles for the local node. Roles set for the node specify which types of resources can be relocated to the node. These roles are selected from the list of all resource types supported on the node (see ''list-supported-roles'' further). The list of roles must be separated by commas and contain no whitespaces. An asterisk (''*'') placed at the beginning of the list stands for "all roles" and means that any supported resource types can be relocated to the node. The asterisk can only be followed by one or more role names prefixed with a tilde (''~'') that excludes a role from "all roles". Examples:  
 +    * ' ' - no resource types can be relocated to the node;  
 +    * ''*'' - all types of resources can be relocated to the node;  
 +    * ''CT,ISCSI'' - only the resource types ''CT'' (containers) and ''ISCSI'' (a custom type) can be relocated to the node;  
 +    * ''*,~CT'' - any supported resource types except ''CT'' can be relocated to the node. 
 +<WRAP center round info 60%> 
 +For details on creating custom resource types, see ''man shaman-scripts''. 
 +</WRAP> 
 +  * ''list-supported-roles'' - Show the list of all roles (resource types) supported on the local node. 
 +  * ''cleanup-broken'' -  Attempt to relocate all broken resources to a local node without starting them. After relocation these resources can be manually migrated to desired nodes. Files of broken resources which cannot be relocated are deleted. 
 +  * ''sync [-D, --dry-run]'' - Synchronize the list of resources registered on the current node with the list of actually available resources. Rarely, the list of resources registered on a node becomes desynchronized with the actual list of clustering resources available on a node. This can happen due to software errors in multiple components. This command can be used to keep the list of resources registered on a node (from shaman's point of view) up to date with the list of resources actually available on the current node. If the ''-D, --dry-run'' option is specified, then ''sync'' only prints the actions, but does not execute them. The command synchronizes resources according to the following rules: 
 +     * if a resource is available on the current node but is not registered in the shaman cluster, then the resource will be registered in the shaman cluster; 
 +     * if a resource is not available on the current node but is registered in the shaman cluster, then the resource will be unregistered from the shaman cluster; 
 +     * if a resource is available on the current node and registered in the shaman cluster but its parameters (e.g., the resource relocation priority) differ, then the resource parameters in the shaman cluster will be updated with the corresponding values from the actual resource available on the current node.
  
-Enable high availability support for the local node. High availability can be enabled for R-Storage clusters only; other shared storage solutions, like NFS, are not supported. The shaman tool automatically gets control over all cluster resources after you enable high availability support. You can use **-r, --ignore-res** option to forbid **shaman** to take control over cluster resources. Use this option only if you know what you are doing.+The ''stat'' and ''top'' commands support the grouped mode when used with ''-g, --group'' option. In this mode, all resources are divided into three groups according to their state: (''Active'', ''Broken'' and ''Pool''). This mode may be useful for monitoring the resources behavior.
  
-**leave** [**-n, --node-ip** //<address>//] [**-N, --node-id** //<ID>//] +The ''stat'' and ''top'' commands can show statistics only for the nodes with specific IP addresses, if the ''-n, --node-ip'' option is specified, or with specific internal IDs, if the ''-N, --node-id'' option is specified. In this case, the commands show the statistics only for the resources hosted on the specified node.
- +
-Disable high availability support. If an IP address or an internal ID is specified, high availability support is disabled for the corresponding node. You can obtain the IP address and internal ID of a node using the **stat** command. +
- +
-**stat** [**-X, --xml**] [**-g, --group**] [**-n, --node-ip** //<address>//] [**-N, --node-id** //\\ +
-<ID>//] +
- +
-Retrieve cluster statistics once and print it in text or XML format (for the latter, specify the **-X, --xml** option). +
- +
-**top** [**-g, --group**] [**-n, --node-ip** //<address>//] [**-N, --node-id** //<ID>//] +
- +
-Show dynamic cluster statistics in real time. +
- +
-**get-config** [**-X, --xml**] +
- +
-Print the global configuration settings in text or XML format. For more details, see **shaman.conf**(5). +
- +
-**set-config** [//key=val// ...] +
- +
-Set the global configuration settings. See shaman.conf(5) for more details. If no //key=val// pairs are specified in the command line, the configuration parameters are read from standard input. +
- +
-**get-config-local** +
- +
-Print the local configuration settings in text format. For more details, see **shaman.conf**(5). +
- +
-**get-roles** [**-X, --xml**] +
- +
-Show the list of roles set for the local node. +
- +
-**set-roles** <//roles//> +
- +
-Set the list of roles for the local node.\\ +
-Roles set for the node specify which types of resources can be relocated to the node. These roles are selected from the list of all resource types supported on the node (see ’list-supported-roles’ further). The list of roles must be separated by commas and contain no whitespaces. An asterisk (’*’) placed at the beginning of the list stands for "all roles" and means that any supported resource types can be relocated to the node. The asterisk can only be followed by one or more role names prefixed with a tilde (’~’) that excludes a role from "all roles".\\ +
-Examples: ’’ - no resource types can be relocated to the node; ’*’ - all types of resources can be relocated to the node; ’CT,ISCSI’ - only the resource types ’CT’ (containers) and ’ISCSI’ (a custom type) can be relocated to the node; ’*,~CT’ - any supported resource types except ’CT’ can be relocated to the node.\\ +
-Note: For details on creating custom resource types, see ’man shaman-scripts’. +
- +
-**list-supported-roles** +
- +
-Show the list of all roles (resource types) supported on the local node. +
- +
-**cleanup-broken** +
- +
-Attempt to relocate all broken resources to a local node without starting them. After relocation these resources can be manually migrated to desired nodes. Files of broken resources which cannot be relocated are deleted. +
- +
-**sync** [**-D, --dry-run**] +
- +
-Synchronize the list of resources registered on the current node with the list of actually available resources.\\ +
-Rarely, the list of resources registered on a node becomes desynchronized with the actual list of clustering resources available on a node. This can happen due to software errors in multiple components. This command can be used to keep the list of resources registered on a node (from shaman’s point of view) up to date with the list of resources actually available on the current node. If the **-D, --dry-run** option is specified, then **sync** only prints the actions, but does not execute them.\\ +
-The command synchronizes resources according to the following rules: +
- +
-- if a resource is available on the current node but is not registered in the shaman cluster, then the resource will be registered in the shaman cluster; +
- +
-- if a resource is not available on the current node but is registered in the shaman cluster, then the resource will be unregistered from the shaman cluster; +
- +
-- if a resource is available on the current node and registered in the shaman cluster but its parameters (e.g., the resource relocation priority) differ, then the resource parameters in the shaman cluster will be updated with the corresponding values from the actual resource available on the current node. +
- +
-The **stat** and **top** commands support the grouped mode when used with **-g, --group** option. In this mode, all resources are divided into three groups according to their state: (**Active**, **Broken** and **Pool**). This mode may be useful for monitoring the resources behavior. +
- +
-The **stat** and **top** commands can show statistics only for the nodes with specific IP addresses, if the **-n, --node-ip** option is specified, or with specific internal IDs, if the **-N, --node-id** option is specified. In this case, the commands show the statistics only for the resources hosted on the specified node.+
  
 ===== INTERACTIVE COMMANDS  ===== ===== INTERACTIVE COMMANDS  =====
  
-The following interactive keyboard commands are available when running the **shaman top** command.+The following interactive keyboard commands are available when running the ''shaman top'' command.
  
-||**g**||Group or ungroup resources by their status.|| +  * ''g'' Group or ungroup resources by their status. 
-||**v**||Show or hide additional information.       || +  * ''v'' Show or hide additional information. 
- +  * ''ENTER'' or ''SPACE'' - Update the screen. 
-**ENTER** or **SPACE** +  * ''q'' or ''Esc'' or ''CTRL-C'' - Quit the command. 
- +  * ''h'' - Show the help screen.
-Update the screen. +
- +
-**q** or **Esc** or **CTRL-C** +
- +
-Quit the command. +
- +
-||**h**||Show the help screen.||+
  
 ===== DISPLAYED FIELDS EXPLANATION  ===== ===== DISPLAYED FIELDS EXPLANATION  =====
  
-The **shaman stat** and **shaman top** commands display the following information: +The ''shaman stat'' and ''shaman top'' commands display the following information:
- +
-**OVERALL STATISTICS**\\ +
-Overview of cluster nodes and resources controlled by **shaman** monitor. **\\ +
-Nodes** +
- +
-Total number of nodes for which high availability is enabled. +
- +
-**Resources** +
- +
-Total number of resources controlled by **shaman**. +
- +
-**NODES STATISTICS**\\ +
-Detailed statistics for each node controlled by **shaman**. **\\ +
-SPECIAL MARKS** +
- +
-Node where you run the **shaman** command is marked with *****. The master node is marked with the **M** letter. +
- +
-**NODE_IP** +
- +
-IP address assigned to the node. +
- +
-**STATUS** +
- +
-State of the node. Cluster resources can be relocated to **Active** nodes only. The possible states are: **\\ +
-Active** -- The node and the **shaman-monitor** daemon are up and running. **\\ +
-Inactive** -- The node or the **shaman-monitor** daemon is down. **\\ +
-No license** -- The R-Virtualization license is not installed on the node. **\\ +
-Evacuating** -- The node has crashed and its resources are being relocated to other nodes by the master instance of the **shaman-monitor** daemon. **\\ +
-Skipped** -- The node has crashed and its resources have not been relocated to other nodes due to the RELOCATION_SKIP_THRESHOLD limit (see shaman.conf(5)). **\\ +
-Unknown** -- Node state cannot be determined. +
- +
-**NODE_ID**+
  
-Internal ID of the node.+''OVERALL STATISTICS'' - Overview of cluster nodes and resources controlled by ''shaman'' monitor.  
 +  * ''Nodes''  - Total number of nodes for which high availability is enabled. 
 +  * ''Resources'' - Total number of resources controlled by ''shaman''.
  
-**ROLES**+''NODES STATISTICS'' - Detailed statistics for each node controlled by ''shaman''. 
  
-Roles of the node.+''SPECIAL MARKS'' - Node where you run the ''shaman'' command is marked with ''*''. The master node is marked with the ''M'' letter.
  
-**RESOURCES**+''NODE_IP'' - IP address assigned to the node.
  
-Number of resources of each type hosted on the node. The resources with the **Broken** status are not taken into account.+''STATUS'' - State of the node. Cluster resources can be relocated to ''Active'' nodes only. The possible states are: 
 +  * ''Active'' -- The node and the ''shaman-monitor'' daemon are up and running.  
 +  * ''Inactive'' -- The node or the ''shaman-monitor'' daemon is down.  
 +  * ''No license'' -- The R-Virtualization license is not installed on the node.  
 +  * ''Evacuating'' -- The node has crashed and its resources are being relocated to other nodes by the master instance of the ''shaman-monitor'' daemon.  
 +  * ''Skipped'' -- The node has crashed and its resources have not been relocated to other nodes due to the RELOCATION_SKIP_THRESHOLD limit (see shaman.conf(5)).  
 +  * ''Unknown'' -- Node state cannot be determined.
  
-**RESOURCES STATISTICS**\\ +''NODE_ID'' - Internal ID of the node.
-Detailed statistics for each resource controlled by **shaman-monitor**. **\\ +
-SPECIAL MARKS**+
  
-Resources waiting for relocation are marked with **P** (’Pool’ state). Resources that shaman-monitor has failed to relocate are marked with **B** (’Broken’ state).+''ROLES'' - Roles of the node.
  
-**OWNER_IP**+''RESOURCES'' - Number of resources of each type hosted on the node. The resources with the ''Broken'' status are not taken into account.
  
-IP address of the node hosting the resource.+''RESOURCES STATISTICS'' - Detailed statistics for each resource controlled by ''shaman-monitor''. 
  
-**OWNER_ID**+''SPECIAL MARKS'' - Resources waiting for relocation are marked with ''P'' (’Pool’ state). Resources that shaman-monitor has failed to relocate are marked with ''B'' (’Broken’ state).
  
-Internal ID of the node hosting the resource.+''OWNER_IP'' - IP address of the node hosting the resource.
  
-**PRIORITY**+''OWNER_ID'' - Internal ID of the node hosting the resource.
  
-A positive value determining the relocation priority of a resource. Resources with a higher priority are relocated first. The default value is 0.+''PRIORITY'' - A positive value determining the relocation priority of a resource. Resources with a higher priority are relocated first. The default value is 0.
  
-**NOTES**\\ +''NOTES'' - The resource statistics usually contains several resource-related fields such as ''ID'', ''PWRR'', and ''NAME''. These fields are defined by the resource descriptions retrieved from the respective resource scripts and can be customized to meet your needs. See **[[domestic:rosplatforma:man:shaman-scripts]]**(5) for details.
-The resource statistics usually contains several resource-related fields such as **ID**, **PWRR**, and **NAME**. These fields are defined by the resource descriptions retrieved from the respective resource scripts and can be customized to meet your needs. See **shaman-scripts**(8) for details.+
  
 ===== FILES  ===== ===== FILES  =====
  
-///etc/shaman/shaman.conf//+''/etc/shaman/shaman.conf''
  
-Main **shaman** configuration file; see **shaman.conf**(5) for details.+Main ''shaman'' configuration file; see **[[domestic:rosplatforma:man:shaman.conf]]**(5) for details.
  
-///usr/share/shaman/enumerate//+''/usr/share/shaman/enumerate''
  
-Main resource controlling script used by **shaman**; see **shaman-scripts**(8) for details.+Main resource controlling script used by ''shaman''; see **shaman-scripts**(8) for details.
  
 ===== DIAGNOSTICS  ===== ===== DIAGNOSTICS  =====
  
-**shaman** returns 0 upon successful execution. If something goes wrong, it returns an appropriate error code:+''shaman'' returns 0 upon successful execution. If something goes wrong, it returns an appropriate error code:
  
 ||1  ||System error.                                                                            | ||1  ||System error.                                                                            |
Line 239: Line 144:
 ===== SEE ALSO  ===== ===== SEE ALSO  =====
  
-**shaman.conf**(5), **shaman-monitor**(8), **shaman-scripts**(8)+**[[domestic:rosplatforma:man:shaman.conf]]**(5), **[[domestic:rosplatforma:man:shaman-monitor]]**(8), **[[domestic:rosplatforma:man:shaman-scripts]]**(8)
  
 ===== COPYRIGHT  ===== ===== COPYRIGHT  =====