diff --git a/doc/README.hb2openais b/doc/README.hb2openais new file mode 100644 index 0000000000..84612d1c9a --- /dev/null +++ b/doc/README.hb2openais @@ -0,0 +1,246 @@ +Heartbeat to OpenAIS cluster stack conversion + +Please read this description entirely before converting to +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 -U + +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 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 openais.conf from ha.cf. + +2. Removal of the nodes section from the CIB. + +3. Upgrade of the CIB to Pacemaker v1.0 (optional) + +4. Addition of pingd resource. + +5. Conversion of ocfs2 filesystem. + +6. Replacement of EVMS2 with LVM2. + +Conversion from the Heartbeat to 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 +should be enforced by the CRM. + +Heartbeat must be down on all nodes. + +The ocfs2 filesystem and EVMS2 resources must be down. + +It is possible to keep other services running: just put all +resources into the unmanaged mode before stopping heartbeat. + +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 + +Do not run this procedure on more than one node! + +1. Generate openais.conf from ha.cf. + +/etc/ha.d/ha.cf is parsed and /etc/ais/openais.conf +correspondingly generated. + +Whereas heartbeat supports several different communication +types (broadcast, unicast, multicast), 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) man +page is the reference documentation. + +Make sure that your network supports IP multicasts. + +OpenAIS does not support serial communication links. + +In addition, an OpenAIS authentication key is generated. + +2. Removal of the nodes section from the CIB. + +Since the nodes UUID are generated by OpenAIS in a different +manner, the nodes section must be removed. This section is +automaticaly generated when the cluster is started. + +If you had node attributes defined in the nodes section, they +will have to be manually recreated. + +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. You may do so by passing the -U option to the +hb2openais.sh program. If this option is not specified, the +program will still ask if you want to upgrade the CIB to the new +version. + +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. Note that +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. + +6. Replacement of EVMS2 with LVM2. + +Skip this in case you don't have EVMS2 resources. + +EVMS2 is replaced by the clustered LVM2. The conversion program +removes all Evmsd resources and converts the EvmsSCC to LVM +resources. + +Please supply the name of the LVM volume group when the program +asks. + +Note on logging + +The CRM still does not share the logging setup with the OpenAIS, +i.e. it does not read the logging stanza from openais.conf. This +will be rectified in future, but in the meantime the logging +configuration has to be replicated in /etc/sysconfig/pacemaker, +for instance: + +USE_LOGD=yes +SYSLOG_FACILITY=local7 + +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/ais start + +Put resources back to the managed mode in case they were +previously unmanaged. + +TODO: What happens to the tunefs.ocfs2 process? We should know +when it's done and stop the cluster stack. + +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. + +TODO: Check effect of hb_uuid files removal on other nodes! They +have to be regenerated and will be different from the nodes +section. Perhaps backup/revert should take place on all nodes. + +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 + +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 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 + +Configuration_Explained.pdf +openais.conf(5)