diff --git a/doc/Makefile.am b/doc/Makefile.am index 3795d14156..7c258fd56a 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,134 +1,141 @@ # # doc: Pacemaker code # # Copyright (C) 2008 Andrew Beekhof # # This program is free software; you can redistribute it and/or # modify it under the terms of the GNU General Public License # as published by the Free Software Foundation; either version 2 # of the License, or (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. # MAINTAINERCLEANFILES = Makefile.in helpdir = $(datadir)/$(PACKAGE) -ascii = crm_cli.txt crm_fencing.txt acls.txt -help_DATA = crm_cli.txt +ascii = crm_fencing.txt acls.txt +asciiman = crm.8.txt +help_DATA = crm.8.txt docbook = Pacemaker_Explained Clusters_from_Scratch doc_DATA = README.hb2openais $(ascii) $(generated_docs) +man8_MANS = crm.8 publican_docs = generated_docs = +generated_mans = DOCBOOK_FORMATS := html-desktop,txt SVG := $(wildcard */en-US/images/pcmk-*.svg) PNGS = $(SVG:%.svg=%-small.png) $(SVG:%.svg=%.png) $(SVG:%.svg=%-large.png) BRAND_PNGS = publican-clusterlabs/en-US/images/title_logo.png \ publican-clusterlabs/en-US/images/image_left.png \ publican-clusterlabs/en-US/images/image_right.png \ publican-clusterlabs/en-US/images/h1-bg.png graphics: $(PNGS) %.png: %.svg inkscape --file=$< --export-dpi=90 -C --export-png=$@ %-small.png: %.svg inkscape --file=$< --export-dpi=45 -C --export-png=$@ %-large.png: %.svg inkscape --file=$< --export-dpi=180 -C --export-png=$@ XML_FILES := $(wildcard *.xml) PNG_FILES := $(wildcard images/*.png) if BUILD_ASCIIDOC -generated_docs += $(ascii:%.txt=%.html) +generated_docs += $(ascii:%.txt=%.html) $(asciiman:%.txt=%.html) +generated_mans += $(asciiman:%.8.txt=%.8) +$(generated_mans): $(asciiman) endif if BUILD_DOCBOOK publican_docs += $(docbook) endif EXTRA_DIST = $(docbook:%=%.xml) %.html: %.txt $(ASCIIDOC) --unsafe --backend=xhtml11 $< +%.8: %.8.txt + a2x -f manpage $< Clusters_from_Scratch_SRCS := $(wildcard Clusters_from_Scratch/*/*.xml) # We have to hardcode the book name # With '%' the test for 'newness' fails Clusters_from_Scratch.txt: $(wildcard Clusters_from_Scratch/en-US/*.xml) @echo Building $(@:%.txt=%) because of $? rm -rf $(@:%.txt=%)/publish/* cd $(@:%.txt=%) && $(PUBLICAN) build --publish --langs=all --formats=$(DOCBOOK_FORMATS) rm -rf $(@:%.txt=%)/tmp touch $@ Pacemaker_Explained.txt: $(wildcard Pacemaker_Explained/en-US/*.xml) @echo Building $(@:%.txt=%) because of $? rm -rf $(@:%.txt=%)/publish/* cd $(@:%.txt=%) && $(PUBLICAN) build --publish --langs=all --formats=$(DOCBOOK_FORMATS) rm -rf $(@:%.txt=%)/tmp touch $@ if BUILD_DOCBOOK docbook_txt = $(docbook:%=%.txt) all-local: $(docbook_txt) */publican.cfg #install-data-local: all-local install-data-local: all-local for book in $(docbook); do \ filelist=`find $$book/publish/* -print`; \ for f in $$filelist; do \ p=`echo $$f | sed s:publish/:: | sed s:Pacemaker/::`; \ if [ -d $$f ]; then \ $(INSTALL) -d 775 $(DESTDIR)$(docdir)/$$p; \ else \ $(INSTALL) -m 644 $$f $(DESTDIR)$(docdir)/$$p; \ fi \ done; \ done endif brand: $(BRAND_PNGS) $(wildcard publican-clusterlabs/en-US/*.xml) cd publican-clusterlabs && publican build --formats=xml --langs=all --publish echo "Installing..." cd publican-clusterlabs && sudo publican install_brand --path=$(datadir)/publican/Common_Content # find publican-clusterlabs -name "*.noarch.rpm" -exec rm -f \{\} \; # cd publican-clusterlabs && $(PUBLICAN) package --binary # find publican-clusterlabs -name "*.noarch.rpm" -exec sudo rpm -Uvh --force \{\} \; www: $(generated_docs) - echo rsync -rtz --progress $(generated_docs) $(ascii) root@www.clusterlabs.org:/var/www/html/doc/ - rsync -rtz --progress $(generated_docs) $(ascii) root@www.clusterlabs.org:/var/www/html/doc/ + echo rsync -rtz --progress $(generated_docs) $(ascii) $(asciiman) root@www.clusterlabs.org:/var/www/html/doc/ + rsync -rtz --progress $(generated_docs) $(ascii) $(asciiman) root@www.clusterlabs.org:/var/www/html/doc/ rm -f $(docbook_txt) make DOCBOOK_FORMATS="pdf,html,html-single,txt,epub" all-local $(generated_docs) $(ascii) echo Uploading current documentation set to clusterlabs.org - rsync -rtz --progress $(generated_docs) $(ascii) root@www.clusterlabs.org:/var/www/html/doc/ + rsync -rtz --progress $(generated_docs) $(ascii) $(asciiman) root@www.clusterlabs.org:/var/www/html/doc/ if BUILD_DOCBOOK for book in $(docbook); do \ echo Uploading $$book...; \ echo "Generated on `date` from version: $(shell hg id -i -t)" > $$book/publish/build-$(PACKAGE_SERIES).txt; \ rsync -rtz --progress $$book/publish/* root@www.clusterlabs.org:/var/www/html/doc/; \ done endif clean-local: - -rm -rf $(generated_docs) $(docbook_txt) + -rm -rf $(generated_docs) $(generated_mans) $(docbook_txt) for book in $(docbook); do rm -rf $$book/tmp $$book/publish; done diff --git a/doc/crm_cli.txt b/doc/crm.8.txt similarity index 91% rename from doc/crm_cli.txt rename to doc/crm.8.txt index a4a17e8033..4af9d7fe21 100644 --- a/doc/crm_cli.txt +++ b/doc/crm.8.txt @@ -1,2343 +1,2379 @@ -CRM CLI (command line interface) tool -====================================== -Dejan_Muhamedagic,_Yan_Gao dejan@suse.de,ygao@novell.com -v0.94, Februar 18, 2010: - -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. +:man source: crm +:man version: 1.1 +:man manual: Pacemaker documentation + +crm(8) +====== + + +NAME +---- +crm - Pacemaker command line interface for configuration and management -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 +SYNOPSIS +-------- +*crm* [-D output_type] [-f file] [-hFRD] [--version] [args] -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. + +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 people to learn about the cluster +made configurations may help newbies 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 `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. -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. +OPTIONS +------- +*-f, --file*='FILE':: + Load commands from the given file. If the file is `-` then + use terminal `stdin`. -Several modes of operation are available to restrict the set of -features depending on the user's proficiency. +*-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. -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. +*-F, --force*:: + Make `crm` proceed with doing changes even though it would + normally ask user to confirm some of them. Mostly useful in + scripts. -The CLI has to be run on one of the cluster nodes. +*-h, --help*:: + Print help page. -.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. +*--version*:: + Print Pacemaker version and build information (Mercurial Hg + changeset hash). -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. -************************** +*-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# up + 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). +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. -We should also define the preferred node to run the service: +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 - 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)# 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 [