diff --git a/doc/crm_cli.txt b/doc/crm_cli.txt index 26c7303812..6a7f1dd47e 100644 --- a/doc/crm_cli.txt +++ b/doc/crm_cli.txt @@ -1,1242 +1,1256 @@ CRM CLI (command line interface) tool ====================================== Dejan_Muhamedagic,_Yan_Gao dejan@suse.de,ygao@novell.com v0.9 The CRM (a.k.a Pacemaker) is a Cluster Resource Manager which implements the cluster configuration provided by the user in CIB (Cluster Information Base). The CIB is a set of instructions coded in XML. Editing the CIB is a challenge, not only due to its complexity and a wide variety of options, but also because XML is not exactly user friendly. .Note ************************** I do understand that there are people capable of dealing with XML without an intermediary. ************************** There are currently three options to manage the CIB, listed here in a decreasing order of user-friendliness: - the GUI (`hb_gui`) - a set of command line tools - `cibadmin(8)` The GUI is very popular and it has recently seen a lot of good development. For some it is going to be (or remain) the first choice in cluster management. The command line tools, lead by `crm_resource(8)`, are capable of performing almost any kind of CIB transformation. The usage is, however, plagued by the notorious weakness common to all UNIX tools: a multitude of options, necessary for operation and yet very hard to remember. Usage is also inconsistent at times. The `cibadmin` is the ultimate CIB management tool: it applies chunks of XML written by the user or generated by another tool to the CIB. Very difficult to use without extensive training. Or should I say drill. May be unnerving as well, in particular due to sometimes cryptic error messages. == Design goals The CLI provides a consistent and unified interface to CIB/cluster management. It uses the command line tools where possible and may resort to XML and `cibadmin` when there is no other option. That is the easiest way to ensure compatibility between different management tools. It may be used either as an interactive shell or for single commands directly on the shell's command line. It is also possible to feed it a set of commands from standard input, thus turning it into a scripting tool. Templates with ready made configurations may help people to learn about the cluster configuration or facilitate testing procedures. The CLI may also be used for the CIB description and generation. A file containing a set of CLI instructions may be applied to the CLI tool to generate a complete CIB. The new shadow CIB feature may also be put to use. The user may work on one of the shadow CIBs and then apply (or commit) it in a single step to the cluster. It should also allow deployment of raw XML which may come either from files or network. Several modes of operation are available to restrict the set of features depending on the user's proficiency. The CLI is line oriented: every command must start and finish on the same line. It is possible to use a continuation character to write one command in two or more lines. The CLI must run on one of the cluster nodes. .Note ************************** Even though all sensible configurations (and most of those that are not) are going to be supported by the CLI, I suspect that it may still happen that certain XML constructs may confuse the tool. When that happens, please file a bug report. The CLI will not try to update the objects it does not understand. Of course, it is always possible to edit such objects in the XML format. ************************** == Introduction to the user interface Arguably the most important aspect of such a program is the user interface. We begin with an informal introduction so that the reader may get acquainted with it and get a general feeling of the tool. It is probably best just to give some examples: 1. Command line (one-shot) use: # crm resource stop www_app 2. Interactive use: # crm crm(live)# resource crm(live) resource# unmanage tetris_1 crm(live) resource# up crm(live)# node standby node4 3. Cluster configuration (interactive mode): # crm crm(live)# configure crm(live) configure# help show [xml] [] edit [xml] [] delete [...] verify verify configuration erase erase configuration commit commit changes to the CIB ra-list [] display avaiable RAs enter enter sub-level primitive define a primitive group define a group clone define cloned resource ms define a master-slave location constrain resource to a location colocation colocate resources order order resources end help crm(live) configure# enter primitive www crm(live) primitive www# help show [xml] edit [xml] erase type [class:[provider:]]type set the primitive type metadata show the RA meta-data param-list display parameters available for the RA meta-list display available meta attributes param name [val] set the parameter value meta name [val] set the meta attribute value op op_type [...] enter the operation end help crm(live) primitive www# type apache crm(live) primitive www# param-list configfile (required) httpd port statusurl options testregex crm(live) primitive www# param configfile /etc/apache2/site0.conf crm(live) primitive www# show primitive www apache configfile=/etc/apache2/site0.conf crm(live) primitive www# meta target_role stopped crm(live) primitive www# end crm(live) configure# 4. Cluster configuration (batch mode): # crm<` denotes a string, `[]` means that the construct is optional, the ellipsis (`...`) signifies that the previous construct may be repeated, `|` means pick one of many, and the rest are literals (strings, `:`, `=`). === `cib` This level is for management of shadow CIBs. All the commands are implemented using `cib_shadow(8)` and the `CIB_shadow` environment variable. The user prompt always includes the name of the currently active shadow or the live CIB. ==== `list` List existing shadow CIBs. Usage: ............... list ............... ==== `new/delete` Create a new shadow CIB or delete an existing one. On `new`, the live cluster configuration is copied. Usage: ............... new delete ............... ==== `reset` Copy the current cluster configuration into the shadow CIB. Usage: ............... reset ............... ==== `use` Choose a CIB. Leave out the CIB name to switch to the running CIB. Usage: ............... use [] ............... ==== `diff` Print differences between the current cluster configuration and the active shadow CIB. Usage: ............... diff ............... ==== `commit` Apply a shadow CIB to the cluster. Usage: ............... commit ............... === `resource` At this level resources may be managed. All (or almost all) commands are implemented with the CRM tools such as `crm_resource(8)`. ==== `status` Print resource status. If the resource parameter is left out status of all resources is printed. Usage: ............... status [] ............... ==== `start/stop` Start/stop a resource using the `target_role` attribute. Usage: ............... start stop ............... ==== `manage/unmanage` Manage/unmanage a resource using the `is_managed` attribute. Usage: ............... manage unmanage ............... ==== `migrate/unmigrate` Migrate a resource to a different node or remove the constraint generated by the previous migrate command. If node is left out, the resource is migrated by creating a constraint which prevents it from running on the current node. Usage: ............... migrate [] unmigrate ............... ==== `param` Show/edit/delete a parameter of a resource. Usage: ............... param set param delete param show ............... Example: ............... param ip_0 show ip ............... ==== `meta` Show/edit/delete a meta attribute of a resource. Currently, all meta attributes of a resource may be managed with other commands such as `resource stop`. Usage: ............... meta set meta delete meta show ............... Example: ............... meta ip_0 set target_role stopped ............... ==== `failcount` Show/edit/delete the failcount of a resource. Usage: ............... failcount set failcount delete failcount show ............... Example: ............... failcount fs_0 delete node2 ............... ==== `cleanup` Cleanup resource status. Typically done after the resource has temporarily failed. If a node is omitted, cleanup on all nodes. If there are many nodes, the command may take a while. Usage: ............... cleanup [] ............... ==== `refresh` Refresh CIB from the LRM status. Usage: ............... refresh [] ............... ==== `reprobe` Probe for resources not started by the CRM. Usage: ............... reprobe [] ............... === `node` Node management and status commands. ==== `status` Show a node status. If the node parameter is omitted then status of all nodes is displayed. Usage: ............... status [] ............... ==== `show` Show a node definition. If the node parameter is omitted then all nodes are shown. Usage: ............... show [] ............... ==== `standby/online` Set a node to standby or online status. Usage: ............... standby online ............... ==== `attribute` Edit node attributes. This kind of attribute should refer to relatively static properties, such as memory size. Usage: ............... attribute set attribute delete attribute show ............... Example: ............... attribute node_1 set memory_size 4096 ............... ==== `status-attr` Edit node attributes which are in the CIB status section, i.e. attributes which hold properties of a more volatile nature. One typical example is attribute generated by the `pingd` utility. Usage: ............... status-attr set status-attr delete status-attr show ............... Example: ............... status-attr node_1 show pingd ............... === `configure` (batch mode) This level enables all CIB object definition commands. The commands from the batch mode may also be entered interactively, but they are better suited for scripts. The configuration is divided into three levels: resources, constraints, and (cluster) properties. Each of these levels support several basic CIB objects. For resources those are: - `primitive` - `group` - `clone` - `ms` (master-slave) There are three types of constraints: - `location` - `colocation` - `order` Finally, there are the cluster properties which is just a set of attributes. The attributes are managed by the `property` command. The changes applied to the current CIB only on ending the configuration session or using the `configure commit` command. ==== `primitive` The primitive command describes a resource. It may be referenced only once in group, clone, or master-slave objects. If it's not referenced, then it is placed as a single resource in the CIB. Operations may be specified in three ways. "Anonymous" as a simple list of "op" specifications. Use that if you don't want to reference the set of operations elsewhere. That's by far the most common way to define operations. If reusing operation sets is desired, use the "operations" keyword along with the id to give the operations set a name and the id-ref to reference another set of operations. Usage: ............... primitive [:[:]] [params = [=...]] [meta = [=...]] [operations id_spec [op op_type [=...] ...]] id_spec :: $id= | $id-ref= op_type :: start | stop | monitor ............... Example: ............... primitive apcfence stonith:apcsmart \ params ttydev=/dev/ttyS0 hostlist="node1 node2" \ op start timeout=60s \ op monitor interval=30m timeout=60s primitive www8 apache \ params configfile=/etc/apache/www8.conf \ operations $id-ref=apache_ops ............... ==== `group` The `group` command creates a group of resources. Usage: ............... group [...] [params = [=...]] [meta = [=...]] ............... Example: ............... group internal_www disk0 fs0 internal_ip apache \ meta target_role=stopped ............... ==== `clone` The `clone` command creates a resource clone. It may contain a single primitive resource or one group of resources. Usage: ............... clone [params = [=...]] [meta = [=...]] ............... Example: ............... clone cl_fence apc_1 \ meta clone_node_max=1 globally_unique=false ............... ==== `ms` (master/slave) The `ms` command creates a master/slave resource type. It may contain a single primitive resource or one group of resources. Usage: ............... ms [params = [=...]] [meta = [=...]] ............... Example: ............... ms disk1 drbd1 \ meta notify=true globally_unique=false ............... ==== `location` `location` defines the preference of nodes for the given resource. The location constraints consist of one or more rules which specify a score to be awarded if the rule matches. Usage: ............... location rule [id_spec] [$role=] : [rule [id_spec] [$role=] : ...] id_spec :: $id= | $id-ref= score :: | | [-]inf expression :: [bool_op ...] | bool_op :: or | and single_exp :: [type:] | type :: string | version | number binary_op :: lt | gt | lte | gte | eq | ne unary_op :: defined | not_defined date_expr :: date_op [] (TBD) ............... Examples: ............... location conn_1 internal_www \ rule 50: #uname eq node1 \ rule pingd: defined pingd location conn_2 dummy_float \ rule -inf: not_defined pingd or pingd lte 0 ............... ==== `colocation` This constraint expresses the placement relation between two resources. Usage: ............... colocation : [:] [:] [symmetrical=] ............... Example: ............... colocation dummy_and_apache -inf: apache dummy ............... ==== `order` This constraint expresses the order of actions on two resources. Usage: ............... order score-type: [:] [:] [symmetrical=] score-type :: advisory | mandatory | ............... Example: ............... order c_apache_1 mandatory: apache:start ip_1 ............... ==== `property` Set the cluster (`crm_config`) options. Usage: ............... property [$id=]