[appendix]

== Upgrading the Configuration from 0.6 ==

=== Preparation ===
indexterm:[Upgrading the Configuration]
indexterm:[Configuration,Upgrading]

indexterm:[Download,DTD]
indexterm:[DTD,Download]

Download the latest
http://hg.clusterlabs.org/pacemaker/stable-1.0/file-raw/tip/xml/crm.dtd[DTD]
and ensure your configuration validates.

=== Perform the upgrade ===

==== Upgrade the software ====

Refer to the appendix: <<ap-upgrade>>

==== Upgrade the Configuration ====

As XML is not the friendliest of languages, it is common for cluster
administrators to have scripted some of their activities. In such
cases, it is likely that those scripts will not work with the new 1.0
syntax.

In order to support such environments, it is actually possible to
continue using the old 0.6 syntax.

The downside is, however, that not all the new features will be
available and there is a performance impact since the cluster must do
a non-persistent configuration upgrade before each transition. So
while using the old syntax is possible, it is not advisable to
continue using it indefinitely.

Even if you wish to continue using the old syntax, it is advisable to
follow the upgrade procedure to ensure that the cluster is able to use
your existing configuration (since it will perform much the same task
internally).

. Create a shadow copy to work with
+
[source,C]
-----
# crm_shadow --create upgrade06
-----
. Verify the configuration is valid indexterm:[Configuration,Verify]indexterm:[Verify,Configuration]
+
[source,C]
-----
# crm_verify --live-check
-----
. Fix any errors or warnings
. Perform the upgrade:
+
[source,C]
-----
# cibadmin --upgrade
-----
. If this step fails, there are three main possibilities:
.. The configuration was not valid to start with - go back to step 2
.. The transformation failed - report a bug or mailto:pacemaker@oss.clusterlabs.org?subject=Transformation%20failed%20during%20upgrade[email the project]
.. The transformation was successful but produced an invalid result footnote:[
The most common reason is ID values being repeated or invalid. Pacemaker 1.0 is much stricter regarding this type of validation.
]
+
If the result of the transformation is invalid, you may see a number of errors from the validation library. If these are not helpful, visit http://clusterlabs.org/wiki/Validation_FAQ and/or try the procedure described below under <<s-upgrade-config-manual>>
+        
. Check the changes
+
[source,C]
-----
# crm_shadow --diff
-----
+
If at this point there is anything about the upgrade that you wish to fine-tune (for example, to change some of the automatic IDs) now is the time to do so. Since the shadow configuration is not in use by the cluster, it is safe to edit the file manually:
+
[source,C]
-----
# crm_shadow --edit
-----
+
This will open the configuration in your favorite editor (whichever is specified by the standard +$EDITOR+ environment variable)
+
. Preview how the cluster will react
+
Test what the cluster will do when you upload the new configuration
+
[source,C]
------
# crm_simulate --live-check --save-dotfile upgrade06.dot -S
# graphviz upgrade06.dot
------
+
Verify that either no resource actions will occur or that you are
happy with any that are scheduled.  If the output contains actions you
do not expect (possibly due to changes to the score calculations), you
may need to make further manual changes.  See
<<s-config-testing-changes>> for further details on how to interpret
the output of `crm_simulate`
+
. Upload the changes
+
[source,C]
-----
# crm_shadow --commit upgrade06 --force
-----
If this step fails, something really strange has occurred. You should report a bug.

[[s-upgrade-config-manual]]
==== Manually Upgrading the Configuration ====

indexterm:[Configuration,Upgrade manually]
It is also possible to perform the configuration upgrade steps manually. To do this

Locate the 'upgrade06.xsl' conversion script or download the latest
version from
https://github.com/ClusterLabs/pacemaker/tree/master/xml/upgrade06.xsl[Git]
          
. Convert the XML blob: indexterm:[XML,Convert]
+
[source,C]
-----
# xsltproc /path/to/upgrade06.xsl config06.xml > config10.xml
-----
+          
. Locate the 'pacemaker.rng' script.
. Check the XML validity: indexterm:[Validate Configuration]indexterm:[Configuration,Validate XML]
+
[source,C]
# xmllint --relaxng /path/to/pacemaker.rng config10.xml

The advantage of this method is that it can be performed without the
cluster running and any validation errors should be more informative
(despite being generated by the same library!) since they include line
numbers.
