diff --git a/doc/Makefile.am b/doc/Makefile.am index 310e60ba8a..8075e0f659 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,184 +1,179 @@ # # 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_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) publican_docs = generated_docs = generated_mans = DOCBOOK_FORMATS := html-desktop,txt DOCBOOK_LANGS := en-US DOTs = $(wildcard */en-US/images/*.dot) SVG = $(wildcard */en-US/images/pcmk-*.svg) $(DOTs:%.dot=%.svg) PNGS = $(SVG:%.svg=%-small.png) $(SVG:%.svg=%.png) $(SVG:%.svg=%-large.png) \ Pacemaker_Explained/en-US/images/Policy-Engine-big.png Pacemaker_Explained/en-US/images/Policy-Engine-small.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=$@ if BUILD_ASCIIDOC -generated_docs += $(ascii:%.txt=%.html) $(asciiman:%.txt=%.html) -generated_mans += $(asciiman:%.8.txt=%.8) -$(generated_mans): $(asciiman) -man8_MANS = $(generated_mans) +generated_docs += $(ascii:%.txt=%.html) if BUILD_DOCBOOK publican_docs += $(docbook) endif endif EXTRA_DIST = $(docbook:%=%.xml) %.html: %.txt $(ASCIIDOC) --unsafe --backend=xhtml11 $< %.8: %.8.txt a2x -L -f manpage $< # Build docbook from asciidoc because XML is a PITA to edit # # Build each chapter as a book (since the numbering isn't right for # articles and only books can have appendicies) and then strip out the # bits we don't want/need # %.xml: %.txt asciidoc -b docbook -d book -o $@ $< sed -i.sed 's/ //' $@ # Fix line endings sed -i.sed 's/\ lang="en"//' $@ # Never specify a language in the chapters sed -i.sed 's/simpara/para/g' $@ # publican doesn't correctly render footnotes with simpara sed -i.sed 's/.*.*//g' $@ # Remove dangling tag sed -i.sed 's/.*preface>//g' $@ # Remove preface elements sed -i.sed 's:::g' $@ # Remove empty title sed -i.sed 's/chapter/section/g' $@ # Chapters become sections, so that books can become chapters sed -i.sed 's/<.*bookinfo.*>//g' $@ # Strip out bookinfo, we don't need it -grep -qis "//' $@ # We just want the appendix tag -grep -vqis "/chapter>/g' $@ # Rename to chapter echo Rebuilt $@ from $< CFS_TXT=$(wildcard Clusters_from_Scratch/en-US/*.txt) CFS_XML=$(CFS_TXT:%.txt=%.xml) # We have to hardcode the book name # With '%' the test for 'newness' fails Clusters_from_Scratch.txt: $(PNGS) $(wildcard Clusters_from_Scratch/en-US/*.xml) $(CFS_XML) @echo Building $(@:%.txt=%) because of $? rm -rf $(@:%.txt=%)/publish/* cd $(@:%.txt=%) && RPM_BUILD_DIR="" $(PUBLICAN) build --publish --langs=$(DOCBOOK_LANGS) --formats=$(DOCBOOK_FORMATS) rm -rf $(@:%.txt=%)/tmp touch $@ PE_TXT=$(wildcard Pacemaker_Explained/en-US/*.txt) PE_XML=$(PE_TXT:%.txt=%.xml) # We have to hardcode the book name # With '%' the test for 'newness' fails Pacemaker_Explained.txt: $(PNGS) $(wildcard Pacemaker_Explained/en-US/*.xml) $(PE_XML) @echo Building $(@:%.txt=%) because of $? rm -rf $(@:%.txt=%)/publish/* cd $(@:%.txt=%) && RPM_BUILD_DIR="" $(PUBLICAN) build --publish --langs=$(DOCBOOK_LANGS) --formats=$(DOCBOOK_FORMATS) rm -rf $(@:%.txt=%)/tmp touch $@ # Update the translation template pot: for book in $(docbook); do \ echo "Updating translation templates in: $$book"; \ ( cd $$book && RPM_BUILD_DIR="" $(PUBLICAN) update_pot ); \ done # Update the actual translations po: for book in $(docbook); do \ echo "Updating translations in: $$book"; \ ( cd $$book && RPM_BUILD_DIR="" $(PUBLICAN) update_po --langs=$(DOCBOOK_LANGS) );\ done 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) $(asciiman) root@www.clusterlabs.org:/var/www/html/doc/ - rsync -rtz --progress $(generated_docs) $(ascii) $(asciiman) root@www.clusterlabs.org:/var/www/html/doc/ + 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/ rm -f $(docbook_txt) make DOCBOOK_FORMATS="pdf,html,html-single,txt,epub" DOCBOOK_LANGS="all" all-local $(generated_docs) $(ascii) echo Uploading current documentation set to clusterlabs.org 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 git log --pretty="format:%h %d" -n 1)" > $$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) $(generated_mans) $(docbook_txt) $(CFS_XML) $(PE_XML) for book in $(docbook); do rm -rf $$book/tmp $$book/publish; done foo: rm -f $(CFS_XML) diff --git a/doc/crm.8.txt b/doc/crm.8.txt deleted file mode 100644 index fec0a53fcb..0000000000 --- a/doc/crm.8.txt +++ /dev/null @@ -1,2401 +0,0 @@ -: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 [