diff --git a/doc/Makefile.am b/doc/Makefile.am index 43528752b9..46d4451b46 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,201 +1,201 @@ # # 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. # include $(top_srcdir)/Makefile.common helpdir = $(datadir)/$(PACKAGE) ascii = crm_fencing.txt acls.txt docbook = Pacemaker_Explained Clusters_from_Scratch Pacemaker_Remote -doc_DATA = README.hb2openais $(ascii) $(generated_docs) +doc_DATA = $(ascii) $(generated_docs) # rsync destination for www targets RSYNC_DEST = root@www.clusterlabs.org:/var/www/html/doc/ publican_docs = generated_docs = generated_mans = ASCIIDOC_CLI_TYPE := pcs DOCBOOK_FORMATS := html-desktop 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 \ Pacemaker_Remote/en-US/images/pcmk-ha-cluster-stack.png \ Pacemaker_Remote/en-US/images/pcmk-ha-remote-stack.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 $(AM_V_IMG)$(INKSCAPE) --file=$< --export-dpi=90 -C --export-png=$@ %-small.png: %.svg $(AM_V_IMG)$(INKSCAPE) --file=$< --export-dpi=45 -C --export-png=$@ %-large.png: %.svg $(AM_V_IMG)$(INKSCAPE) --file=$< --export-dpi=180 -C --export-png=$@ if BUILD_ASCIIDOC generated_docs += $(ascii:%.txt=%.html) if BUILD_DOCBOOK publican_docs += $(docbook) endif endif EXTRA_DIST = $(docbook:%=%.xml) %.html: %.txt $(AM_V_ASCII)$(ASCIIDOC) --unsafe --backend=xhtml11 $< SHARED_TXT=$(wildcard shared/en-US/*.txt) SHARED_XML=$(SHARED_TXT:%.txt=%.xml) CFS_SHARED_TXT=$(addprefix shared/en-US/,pacemaker-intro.txt) CFS_SHARED_XML=$(CFS_SHARED_TXT:%.txt=%.xml) CFS_TXT=$(wildcard Clusters_from_Scratch/en-US/*.txt) CFS_XML=$(CFS_TXT:%.txt=%.xml) $(CFS_XML): $(CFS_SHARED_XML) # We have to hardcode the book name # With '%' the test for 'newness' fails Clusters_from_Scratch.build: $(PNGS) $(wildcard Clusters_from_Scratch/en-US/*.xml) $(CFS_XML) $(CFS_SHARED_XML) $(PCMK_V) @echo Building $(@:%.build=%) because of $? rm -rf $(@:%.build=%)/publish/* $(AM_V_PUB)cd $(@:%.build=%) && RPM_BUILD_DIR="" $(PUBLICAN) build --publish --langs=$(DOCBOOK_LANGS) --formats=$(DOCBOOK_FORMATS) $(PCMK_quiet) rm -rf $(@:%.build=%)/tmp touch $@ PE_SHARED_TXT=$(addprefix shared/en-US/,pacemaker-intro.txt) PE_SHARED_XML=$(PE_SHARED_TXT:%.txt=%.xml) PE_TXT=$(wildcard Pacemaker_Explained/en-US/*.txt) PE_XML=$(PE_TXT:%.txt=%.xml) $(PE_XML): $(PE_SHARED_XML) # We have to hardcode the book name # With '%' the test for 'newness' fails Pacemaker_Explained.build: $(PNGS) $(wildcard Pacemaker_Explained/en-US/*.xml) $(PE_XML) $(PE_SHARED_XML) $(PCMK_V) @echo Building $(@:%.build=%) because of $? rm -rf $(@:%.build=%)/publish/* $(AM_V_PUB)cd $(@:%.build=%) && RPM_BUILD_DIR="" $(PUBLICAN) build --publish --langs=$(DOCBOOK_LANGS) --formats=$(DOCBOOK_FORMATS) $(PCMK_quiet) rm -rf $(@:%.build=%)/tmp touch $@ PR_TXT=$(wildcard Pacemaker_Remote/en-US/*.txt) PR_XML=$(PR_TXT:%.txt=%.xml) # We have to hardcode the book name # With '%' the test for 'newness' fails Pacemaker_Remote.build: $(PNGS) $(wildcard Pacemaker_Remote/en-US/*.xml) $(PR_XML) $(PCMK_V) @echo Building $(@:%.build=%) because of $? rm -rf $(@:%.build=%)/publish/* $(AM_V_PUB)cd $(@:%.build=%) && RPM_BUILD_DIR="" $(PUBLICAN) build --publish --langs=$(DOCBOOK_LANGS) --formats=$(DOCBOOK_FORMATS) $(PCMK_quiet) rm -rf $(@:%.build=%)/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: pot for book in $(docbook); do \ echo "Updating translations in: $$book"; \ ( cd $$book && RPM_BUILD_DIR="" $(PUBLICAN) update_po --langs=all );\ done if BUILD_DOCBOOK docbook_build = $(docbook:%=%.build) all-local: $(docbook_build) */publican.cfg 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 -m 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 \{\} \; pdf: make DOCBOOK_FORMATS="pdf" ASCIIDOC_CLI_TYPE=$(ASCIIDOC_CLI_TYPE) all-local www: clean-local $(generated_docs) $(ascii) make www-cli rsync -rtz --progress $(generated_docs) $(ascii) $(asciiman) $(RSYNC_DEST) www-pcs: www-cli www-cli: for book in $(docbook); do \ sed -i.sed 's@brand:.*@brand: clusterlabs@' $$book/publican.cfg; \ sed -i.sed 's@version:.*@version: $(PACKAGE_SERIES)-$(ASCIIDOC_CLI_TYPE)@' $$book/publican.cfg; \ done make DOCBOOK_FORMATS="pdf,html,html-single,epub" DOCBOOK_LANGS="all" ASCIIDOC_CLI_TYPE=$(ASCIIDOC_CLI_TYPE) all-local echo Uploading current $(PACKAGE_SERIES)-$(ASCIIDOC_CLI_TYPE) documentation set to clusterlabs.org 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)-$(ASCIIDOC_CLI_TYPE).txt; \ for lang in `ls -1 $$book/publish | grep [a-z][a-z]-[A-Z][A-Z]`; do \ mv $$book/publish/$$lang/Pacemaker/$(PACKAGE_SERIES)-$(ASCIIDOC_CLI_TYPE)/epub/$$book/Pacemaker-1.1{-$(ASCIIDOC_CLI_TYPE),}-$$book-$$lang.epub; \ mv $$book/publish/$$lang/Pacemaker/$(PACKAGE_SERIES)-$(ASCIIDOC_CLI_TYPE)/pdf/$$book/Pacemaker-1.1{-$(ASCIIDOC_CLI_TYPE),}-$$book-$$lang.pdf; \ done; \ rsync -rtz --progress $$book/publish/* $(RSYNC_DEST); \ sed -i.sed 's@version:.*@version: $(PACKAGE_SERIES)@' $$book/publican.cfg; \ done endif clean-local: -rm -rf $(generated_docs) $(generated_mans) $(docbook_build) -rm -rf $(SHARED_XML) $(CFS_XML) $(PE_XML) $(PR_XML) for book in $(docbook); do rm -rf $$book/tmp $$book/publish; done diff --git a/doc/README.hb2openais b/doc/README.hb2openais deleted file mode 100644 index 9470e56ded..0000000000 --- a/doc/README.hb2openais +++ /dev/null @@ -1,281 +0,0 @@ -Heartbeat to Corosync/OpenAIS cluster stack conversion -============================================= - -Please read this description entirely before converting to -Corosync/OpenAIS. Every possible precaution was taken to preclude -problems. Still, you should run the conversion only when you -understood all the steps and the consequences. - -You need to know your cluster in detail. The conversion program -will inform you about changes it makes. It is up to you to verify -that the changes are meaningful. - -Testing the conversion ----------------------- - -It is possible (and highly recommended) to test the conversion -with your heartbeat configuration without making any changes. -This way you will get acquainted with the process and make sure -that the conversion is done properly. - -Create a test directory and copy ha.cf, logd.cf, cib.xml, and -hostcache to it: - -$ mkdir /tmp/hb2openais-testdir -$ cp /etc/ha.d/ha.cf /tmp/hb2openais-testdir -$ cp /var/lib/heartbeat/hostcache /tmp/hb2openais-testdir -$ cp /etc/logd.cf /tmp/hb2openais-testdir -$ sudo cp /var/lib/heartbeat/crm/cib.xml /tmp/hb2openais-testdir - -Run the test conversion: - -$ /usr/lib/heartbeat/hb2openais.sh -T /tmp/hb2openais-testdir - -or - -$ /usr/lib/heartbeat/hb2openais.sh -C -T /tmp/hb2openais-testdir - -to produce corosync.conf. - -Here is the scripts usage: - -usage: hb2openais.sh [-UF] [-u user] [-T directory] [revert] - - -U: skip upgrade the CIB to v1.0 - -F: force conversion despite it being done beforehand - -u user: a user to sudo with (otherwise, you'd - have to run this as root) - -C: force conversion to corosync (default is openais) - -T directory: a directory containing ha.cf/logd.cf/cib.xml/hostcache - (use for testing); with this option files are not - copied to other nodes and there are no destructive - commands executed; you may run as unprivileged uid - -Note: You can run the test as many times as you want on the same -test directory. Copy files just once. - -Note: The directory where hb2openais.sh resides may be different, -e.g. /usr/lib64/heartbeat. - -Read and verify the resulting corosync.conf/openais.conf and -cib-out.xml: - -$ cd /tmp/hb2openais-testdir -$ less openais.conf -$ crm_verify -V -x cib-out.xml - -The conversion takes several stages: - -1. Generate corosync.conf or openais.conf from ha.cf. - -2. Rename nodes ids. - -3. Upgrade of the CIB to Pacemaker v1.0 (optional) - -4. Addition of pingd resource. - -5. Conversion of ocfs2 filesystem. - -6. Conversion of EVMS2 CSM containers to cLVM2 volumes. - -7. Replacement of EVMS2 with clvmd. - -Conversion from the Heartbeat to the Corosync/OpenAIS cluster -stack is implemented in hb2openais.sh which is part of the -pacemaker package. - -Prerequisites -------------- - -/etc/ha.d/ha.cf must be equal on all nodes. - -/var/lib/heartbeat/crm/cib.xml must be equal on all nodes. This -is enforced by the CRM and users should refrain from making -manual changes there. - -The ocfs2 filesystems must not be mounted. - -sshd running on all nodes with access allowed for root. - -The conversion process ----------------------- - -This procedure is supposed to be run on one node only. Although -the main cluster configuration (the CIB) is automatically -replicated, there are some files which have to be copied by other -means. For that to work, we need sshd running on all nodes and -root access working. - -For some operations root privileges are required. Either run -this script as the root user or, if you have a working sudo -setup, specify the privileged user (normally root) using the -u -option: - -$ /usr/lib/heartbeat/hb2openais.sh -u root - -NB: Do not run this procedure on more than one node! - -1. Generate corosync.conf or openais.conf from ha.cf. - -/etc/ha.d/ha.cf is parsed and /etc/ais/openais.conf or -/etc/corosync/corosync.conf correspondingly generated. - -Whereas heartbeat supports several different communication -types (broadcast, unicast, multicast), Corosync/OpenAIS uses only -multicasting. The conversion tries to create equivalent media, -but with some network configurations it may produce wrong -results. Pay particular attention to the "interface" -sub-directive of the "totem" directive. The openais.conf(5) or -corosync.conf(5) man page is the reference documentation. - -Make sure that your network supports IP multicasts. - -Corosync/OpenAIS does not support serial communication links. - -In addition, an Corosync/OpenAIS authentication key is generated -if authentication has been used in Heartbeat. Corosync key -generation may take some time while corosync-keygen gathers -enough entropy for the key. - -NB: corosync.conf is created with compatibility set to whitetank. - -2. Rename nodes ids. - -Since the nodes UUID are generated by Corosync/OpenAIS in a different -manner, the id fields of nodes must be renamed to the node uname. - -3. Upgrade of the CIB to Pacemaker v1.0 (optional) - -There are significant changes introduced in the CIB since -heartbeat versions before and including 2.1.4 and the previous -pacemaker stable version 0.6. The new CRM in pacemaker still -supports the old CIB, but it is recommended to convert to the new -version. The hb2openais.sh program performs the upgrade by -default. This may be skipped by specifying the -U option. - -If you don't convert to the new CIB version, the new crm shell -and configuration tool will not work. - -4. Addition of pingd resource. - -In heartbeat the pingd daemon could be controlled by the -heartbeat itself through the respawn ha.cf directive. Obviously, -it is not possible anymore, so a pingd resource has to be created -in the CIB. Furthermore, hosts from the "ping" directives (the -"ping" nodes) are inserted into the "host_list" pingd resource -attribute. - -5. Conversion of ocfs2 filesystem. - -The ocfs2 filesystem is closely related to the cluster stack -used. It must be converted if the stack is changed. The -conversion script will do this automatically for you. For this -step it will start the cluster stack. The conversion is performed -by the tunefs.ocfs2 program: - - tunefs.ocfs2 --update-cluster-stack - -For more details on ocfs2 conversion refer to the ocfs2 -documentation. - -Skip the following two items in case you don't have EVMS2 CSM -containers. - -6. Conversion of EVMS2 CSM containers to cLVM2 volumes. - -All EVMS2 CSM containers found on the system are converted by -csm-converter (see README.csm-converter for more details). - -For volume groups referenced in existing resources the CIB -(/dev/evms//lvm2//), new LVM -resources are created. Order and collocation constraints are -created for those resources and new LVM resources to ensure -proper start/stop order and resource placement. - -7. Non-LVM EVMS2 - -Skip this in case you don't have EVMS2 resources. - -It is not possible to deal with this on a SLE11 system, so you -should convert it to a compatibility volume on SLES10, which -would turn the it into a LVM2 volume group. The CIB then should -be modified accordingly. - -Enforcing conversion --------------------- - -There is a simple mechanism which prevents running the conversion -process twice in a row. If you know what you are doing, it is -possible to force the conversion using the -F option. - -After the conversion --------------------- - -Once the conversion has been finished, you may start the new -cluster stack: - -# /etc/init.d/openais start (for SLE11 HAE >=SP1 too) - -or - -# /etc/init.d/corosync start - -Put resources back to the managed mode in case they were -previously unmanaged. - -Backup ------- - -The conversion procedure also creates backup of all affected -files. It is possible to revert to the version from the time of -backup: - -# /usr/lib/heartbeat/hb2openais.sh revert - -Note that the revert process is executed only on the node on -which the conversion took place. - -NB: hostcache and hb_uuid files (in /var/lib/heartbeat) are not -removed. They are not used by Corosync/OpenAIS, hence, once -you're content with the conversion, you may safely remove them. - -Affected files --------------- - -All file processing is done on the node where conversion runs. - -The CIB is the only file which is converted: - -/var/lib/heartbeat/crm/cib.xml - -The CIB is removed on all other nodes. - -The following files are generated: - -/etc/ais/openais.conf -/etc/ais/authkey - -or - -/etc/corosync/corosync.conf -/etc/corosync/authkey - -The following files are removed on all nodes: - -/var/lib/heartbeat/crm/cib.xml.sig -/var/lib/heartbeat/crm/cib.xml.last -/var/lib/heartbeat/crm/cib.xml.sig.last -/var/lib/heartbeat/hostcache -/var/lib/heartbeat/hb_uuid - -The Corosync/OpenAIS specific files are copied to all nodes using ssh. - -The CIB is automatically replicated by the CRM and it is not -copied to other nodes. - -References ----------- - -http://www.clusterlabs.org/doc/en-US/Pacemaker/1.0/html/Pacemaker_Explained -openais.conf(5) -corosync.conf(5)