:man source: crm :man version: 1.1 :man manual: Pacemaker documentation crm(8) ====== NAME ---- crm - Pacemaker command line interface for configuration and management SYNOPSIS -------- *crm* [-D output_type] [-f file] [-hFRDw] [--version] [args] DESCRIPTION ----------- Pacemaker configuration is stored in a CIB file (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. The `crm` shell alleviates this issue significantly by introducing small and simple configuration language. The CIB is translated into this language on the fly. `crm` is also a management tool. For management tasks it relies almost exclusively on other command line tools, such as `crm_resource(8)` or `crm_attribute(8)`. Use of these programs 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. `crm` tries to present a consistent interface to the user and to hide the arcane detail. 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 newbies learn about the cluster configuration or facilitate testing procedures. The `crm` shell 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 continuation character is commonly used when displaying configurations. OPTIONS ------- *-f, --file*='FILE':: Load commands from the given file. If the file is `-` then use terminal `stdin`. *-D, --display=*'OUTPUT_TYPE':: Choose one of the output options: `plain`, `color`, or `uppercase`. The default is `color` if the terminal emulation supports colors. Otherwise, `plain` is used. *-F, --force*:: Make `crm` proceed with doing changes even though it would normally ask user to confirm some of them. Mostly useful in scripts. *-w, --wait*:: Make `crm` wait for the transition to finish. Applicable only for commands such as "resource start." *-h, --help*:: Print help page. *--version*:: Print Pacemaker version and build information (Mercurial Hg changeset hash). *-R, --regression-tests*:: Run in the regression test mode. Used mainly by the regression testing suite. *-d, --debug*:: Print some debug information. Used by developers. [Not yet refined enough to print useful information for other users.] == 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# end crm(live)# node standby node4 3. Cluster configuration: # crm< apache filesystem virtual-ip crm(live)configure template# new web apache INFO: pulling in template apache INFO: pulling in template virtual-ip crm(live)configure template# list web2-d web2 vip2 web3 vip web ............... We enter the `template` level from `configure`. Use the `list` command to show templates available on the system. The `new` command creates a configuration from the `apache` template. You can use tab completion to pick templates. Note that the apache template depends on a virtual IP address which is automatically pulled along. The `list` command shows the just created `web` configuration, among other configurations (I hope that you, unlike me, will use more sensible and descriptive names). The `show` command, which displays the resulting configuration, may be used to get an idea about the minimum required changes which have to be done. All `ERROR` messages show the line numbers in which the respective parameters are to be defined: ............... crm(live)configure template# show ERROR: 23: required parameter ip not set ERROR: 61: required parameter id not set ERROR: 65: required parameter configfile not set crm(live)configure template# edit ............... The `edit` command invokes the preferred text editor with the `web` configuration. At the top of the file, the user is advised how to make changes. A good template should require from the user to specify only parameters. For example, the `web` configuration we created above has the following required and optional parameters (all parameter lines start with `%%`): ............... $ grep -n ^%% ~/.crmconf/web 23:%% ip 31:%% netmask 35:%% lvs_support 61:%% id 65:%% configfile 71:%% options 76:%% envfiles ............... These lines are the only ones that should be modified. Simply append the parameter value at the end of the line. For instance, after editing this template, the result could look like this (we used tabs instead of spaces to make the values stand out): ............... $ grep -n ^%% ~/.crmconf/web 23:%% ip 192.168.1.101 31:%% netmask 35:%% lvs_support 61:%% id websvc 65:%% configfile /etc/apache2/httpd.conf 71:%% options 76:%% envfiles ............... As you can see, the parameter line format is very simple: ............... %% ............... After editing the file, use `show` again to display the configuration: ............... crm(live)configure template# show primitive virtual-ip ocf:heartbeat:IPaddr \ params ip="192.168.1.101" primitive apache ocf:heartbeat:apache \ params configfile="/etc/apache2/httpd.conf" monitor apache 120s:60s group websvc \ apache virtual-ip ............... The target resource of the apache template is a group which we named `websvc` in this sample session. This configuration looks exactly as you could type it at the `configure` level. The point of templates is to save you some typing. It is important, however, to understand the configuration produced. Finally, the configuration may be applied to the current crm configuration (note how the configuration changed slightly, though it is still equivalent, after being digested at the `configure` level): ............... crm(live)configure template# apply crm(live)configure template# cd .. crm(live)configure# show node xen-b node xen-c primitive apache ocf:heartbeat:apache \ params configfile="/etc/apache2/httpd.conf" \ op monitor interval="120s" timeout="60s" primitive virtual-ip ocf:heartbeat:IPaddr \ params ip="192.168.1.101" group websvc apache virtual-ip ............... Note that this still does not commit the configuration to the CIB which is used in the shell, either the running one (`live`) or some shadow CIB. For that you still need to execute the `commit` command. To complete our example, we should also define the preferred node to run the service: ............... crm(live)configure# location websvc-pref websvc 100: xen-b ............... If you are not happy with some resource names which are provided by default, you can rename them now: ............... crm(live)configure# rename virtual-ip intranet-ip crm(live)configure# show node xen-b node xen-c primitive apache ocf:heartbeat:apache \ params configfile="/etc/apache2/httpd.conf" \ op monitor interval="120s" timeout="60s" primitive intranet-ip ocf:heartbeat:IPaddr \ params ip="192.168.1.101" group websvc apache intranet-ip location websvc-pref websvc 100: xen-b ............... To summarize, working with templates typically consists of the following steps: - `new`: create a new configuration from templates - `edit`: define parameters, at least the required ones - `show`: see if the configuration is valid - `apply`: apply the configuration to the `configure` level === Tab completion The `crm` makes extensive use of the tab completion of `readline`. The completion is both static (i.e. for `crm` commands) and dynamic. The latter takes into account the current status of the cluster or information from installed resource agents. Sometimes, completion may also be used to get short help on resource parameters. Here a few examples: ............... crm(live)# resource crm(live)resource# bye failcount move restart unmigrate cd help param show unmove cleanup list promote start up demote manage quit status utilization end meta refresh stop exit migrate reprobe unmanage crm(live)resource# end crm(live)# configure crm(live)configure# primitive fence-1 heartbeat: lsb: ocf: stonith: crm(live)configure# primitive fence-1 stonith: apcmaster external/ippower9258 fence_legacy apcmastersnmp external/kdumpcheck ibmhmc apcsmart external/libvirt ipmilan baytech external/nut meatware bladehpi external/rackpdu null cyclades external/riloe nw_rpc100s drac3 external/sbd rcd_serial external/drac5 external/ssh rps10 external/dracmc-telnet external/ssh-bad ssh external/hmchttp external/ssh-slow suicide external/ibmrsa external/vmware wti_mpc external/ibmrsa-telnet external/xen0 wti_nps external/ipmi external/xen0-ha 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= ............... [[SEMCHK]] === Configuration semantic checks Resource definitions may be checked against the meta-data provided with the resource agents. These checks are currently carried out: - are required parameters set - existence of defined parameters - timeout values for operations The parameter checks are obvious and need no further explanation. Failures in these checks are treated as configuration errors. The timeouts for operations should be at least as long as those recommended in the meta-data. Too short timeout values are a common mistake in cluster configurations and, even worse, they often slip through if cluster testing was not thorough. Though operation timeouts issues are treated as warnings, make sure that the timeouts are usable in your environment. Note also that the values given are just _advisory minimum_---your resources may require longer timeouts. User may tune the frequency of checks and the treatment of errors by the <> and <> preferences. Note that if the `check-frequency` is set to `always` and the `check-mode` to `strict`, errors are not tolerated and such configuration cannot be saved. === Access Control Lists (ACL) It is desirable to allow users fine grained access to the cluster and not just ``all or nothing:'' all being the two ultimate power ids `root` and `hacluster`. Access control lists consist of an ordered set of access rules. Each rule allows read or write access or denies access completely. Rules are typically combined to produce a specific role. Then, users may be assigned a role. For instance, this is a role which defines a set of rules allowing management of a single resource: ............... role bigdb_admin \ write meta:bigdb:target-role \ write meta:bigdb:is-managed \ write location:bigdb \ read ref:bigdb ............... The first two rules allow modifying the `target-role` and `is-managed` meta attributes which effectively enables users in this role to stop/start and manage/unmanage the resource. The constraints write access rule allows moving the resource around. Finally, the user is granted read access to the resource definition. For proper operation of all Pacemaker programs, it is advisable to add the following role to all users: ............... role read_all \ read cib ............... For finer grained read access try with the rules listed in the following role: ............... role basic_read \ read node attribute:uname \ read node attribute:type \ read property \ read status ............... It is however possible that some Pacemaker programs (e.g. `ptest`) may not function correctly if the whole CIB is not readable. Some of the ACL rules in the examples above are expanded by the shell to XPath specifications. For instance, `meta:bigdb:target-role` is a shortcut for `//primitive[@id='bigdb']/meta_attributes/nvpair[@name='target-role']`. You can see the expansion by showing XML: ............... crm(live) configure# show xml bigdb_admin ... ............... Many different XPath expressions can have equal meaning. For instance, the following two are equal, but only the first one is going to be recognized as shortcut: ............... //primitive[@id='bigdb']/meta_attributes/nvpair[@name='target-role'] //resources/primitive[@id='bigdb']/meta_attributes/nvpair[@name='target-role'] ............... XPath is a powerful language, but you should try to keep your ACL xpaths simple and the builtin shortcuts should be used whenever possible. == 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, `:`, `=`). === `status` Show cluster status. The status is displayed by `crm_mon`. Supply additional arguments for more information or different format. See `crm_mon(8)` for more details. Usage: ............... status [