diff --git a/doc/crm_cli.txt b/doc/crm_cli.txt index 9cfe18e2a7..b25ba18669 100644 --- a/doc/crm_cli.txt +++ b/doc/crm_cli.txt @@ -1,1251 +1,1261 @@ 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 more computer than 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 or a file, 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 has to be 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: # crm< bye exit manage param show unmanage cd failcount meta quit start unmigrate cleanup help migrate refresh status unmove end list move reprobe stop up crm(live)# configure crm(live)configure# primitive fence-1 heartbeat: lsb: ocf: stonith: crm(live)configure# primitive fence-1 stonith:ipmilan params auth= hostname= ipaddr= login= password= port= priv= crm(live)configure# primitive fence-1 stonith:ipmilan params auth= auth* (string) The authorization type of the IPMI session ("none", "straight", "md2", or "md5") crm(live)configure# primitive fence-1 stonith:ipmilan params auth= ............... == Reference We define a small and simple language. Most commands consist of just a list of simple tokens. The only complex constructs are found at the `configure` level. The syntax is described in a somewhat informal manner: `<>` 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` (shadow CIBs) This level is for management of shadow CIBs. It is available both at the top level and the `configure` level. 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 ............... === `ra` This level contains commands which show various information about the installed resource agents. It is available both at the top level and at the `configure` level. ==== `classes` Print all resource agents' classes and, where appropriate, a list of available providers. Usage: ............... classes ............... ==== `list` List available resource agents for the given class. If the class is `ocf`, supply a provider to get agents which are available only from that provider. Usage: ............... list [] ............... Example: ............... list ocf pacemaker ............... ==== `meta` Show the meta-data of a resource agent type. This is where users can find information on how to use a resource agent. Usage: ............... meta [] ............... Example: ............... meta apache ocf meta ipmilan stonith ............... ==== `providers` List providers for a resource agent type. Usage: ............... providers ............... Example: ............... providers apache ............... === `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` (`show`, `list`) 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` (`move`/`unmove`) 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. ==== `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. The node parameter defaults to the node where the command is run. Usage: ............... standby [] online [] ............... ==== `delete` Delete a node. This command will remove the node from the CIB and, in case the heartbeat stack is running, run hb_delnode too. Usage: ............... delete ............... ==== `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 ............... === `options` The user may set various options for the CLI program itself. ==== `skill-level` Based on the skill-level setting, the user is allowed to use only a subset of commands. There are three levels: operator, administrator, and expert. The operator level allows only commands at the `resource` and `node` levels, but not editing or deleting resources. The administrator may do that and may also configure the cluster at the `configure` level and manage the shadow CIBs. The expert may do all. Usage: ............... skill-level level level :: operator | administrator | expert ............... ==== `user` Sufficient privileges are necessary in order to manage a cluster: programs such as `crm_verify` or `crm_resource` and, ultimately, `cibadmin` have to be run either as `root` or as the CRM owner user (typically `hacluster`). You don't have to worry about that if you run `crm` as `root`. A more secure way is to run the program with your usual privileges, set this option to the appropriate user (such as `hacluster`), and setup the `sudoers` file. Usage: ............... user system-user ............... Example: ............... user hacluster ............... ==== `editor` The `edit` command invokes an editor. Use this to specify your prefered editor program. If not set, it will default to either the value of the `EDITOR` environment variable or to one of the standard UNIX editors (`vi`,`emacs`,`nano`). Usage: ............... editor program ............... Example: ............... editor vim ............... ==== `pager` The `view` command displays text through a pager. Use this to specify your prefered pager program. If not set, it will default to either the value of the `PAGER` environment variable or to one of the standard UNIX system pagers (`less`,`more`,`pg`). ==== `show` Display all current settings. ==== `save` Save current settings to the rc file (`$HOME/.crm.rc`). On further `crm` runs, the rc file is automatically read and parsed. === `configure` This level enables all CIB object definition commands. The configuration may be logically divided into four parts: nodes, resources, constraints, and (cluster) properties and attributes. Each of these commands support one or more basic CIB objects. Nodes and attributes describing nodes are managed using the `node` command. Commands for resources are: - `primitive` - `monitor` - `group` - `clone` - `ms`/`master` (master-slave) There are three types of constraints: - `location` - `colocation` - `order` Finally, there are the cluster properties, resource meta attributes defaults, and operations defaults. All are just a set of attributes. These attributes are managed by the following commands: - `property` - `rsc_defaults` - `op_defaults` The changes applied to the current CIB only on ending the configuration session or using the `commit` command. ==== `node` The node command describes a cluster node. Nodes in the CIB are commonly created automatically by the CRM. Hence, you should not need to deal with nodes unless you also want to define node attributes. Note that it is also possible to manage node attributes at the `node` level. Usage: ............... node [:] [attributes = [=...]] type :: normal | member | ping ............... Example: ............... node node1 node big_node attributes memory=64 ............... ==== `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. +Operation's attributes which are not recognized are saved as +instance attributes of that operation. A typical example is +`OCF_CHECK_LEVEL`. + Usage: ............... primitive [:[:]] [params attr_list] [meta attr_list] [operations id_spec] [op op_type [=...] ...] attr_list :: [$id=] = [=...] | $id-ref= 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 + + primitive db0 mysql \ + params config=/etc/mysql/db0.conf \ + op monitor interval=60s \ + op monitor interval=300s OCF_CHECK_LEVEL=10 ............... ==== `monitor` Monitor is by far the most common operation. It is possible to add it without editing the whole resource. Also, long primitive definitions may be a bit uncluttered. In order to make this command as concise as possible, less common operation attributes are not available. If you need them, then use the `op` part of the `primitive` command. Usage: ............... monitor [:] [:] ............... Example: ............... monitor apcfence 60m:60s ............... Note that after executing the command, the monitor operation may be shown as part of the primitive definition. ==== `group` The `group` command creates a group of resources. Usage: ............... group [...] [meta attr_list] [params attr_list] attr_list :: [$id=] = [=...] | $id-ref= ............... 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 [meta attr_list] [params attr_list] attr_list :: [$id=] = [=...] | $id-ref= ............... Example: ............... clone cl_fence apc_1 \ meta clone-node-max=1 globally-unique=false ............... ==== `ms` (`master`) The `ms` command creates a master/slave resource type. It may contain a single primitive resource or one group of resources. Usage: ............... ms [meta attr_list] [params attr_list] attr_list :: [$id=] = [=...] | $id-ref= ............... Example: ............... ms disk1 drbd1 \ meta notify=true globally-unique=false ............... .Note on `id-ref` usage **************************** Instance or meta attributes (`params` and `meta`) may contain a reference to another set of attributes. In that case, no other attributes are allowed. Since attribute sets' ids, though they do exist, are not shown in the `crm`, it is also possible to reference an object instead of an attribute set. `crm` will automatically replace such a reference with the right id: ............... crm(live)configure# primitive a2 www-2 meta $id-ref=a1 crm(live)configure# show a2 primitive a2 ocf:heartbeat:apache \ meta $id-ref="a1-meta_attributes" [...] ............... It is advisable to give meaningful names to attribute sets which are going to be referenced. **************************** ==== `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 {node_pref|rules} node_pref :: : rules :: 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 100: node1 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` (`collocation`) This constraint expresses the placement relation between two resources. Usage: ............... colocation : [:] [:] ............... 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=]