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/<csm-container>/lvm2/<vgname>/<lvname>), 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)
