[appendix]

== Upgrading the Configuration ==

This process was originally written for the upgrade from 0.6.'x' to 1.'y',
but the concepts should apply for any upgrade involving a change in
the XML schema version.

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

=== 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 XML
syntax.

In order to support such environments, it is actually possible to
continue using the old XML 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 (except for the last step) 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
+
-----
# crm_shadow --create upgrade06
-----
. Verify the configuration is valid indexterm:[Configuration,Verify]indexterm:[Verify,Configuration]
+
-----
# crm_verify --live-check
-----
. Fix any errors or warnings
. Perform the upgrade:
+
-----
# 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 the
http://clusterlabs.org/wiki/Validation_FAQ[Validation FAQ wiki page] and/or try
the procedure described below under <<s-upgrade-config-manual>>
+        
. Check the changes
+
-----
# 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:
+
-----
# 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:
+
------
# 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` and `graphviz`.
+
. Upload the changes
+
-----
# crm_shadow --commit upgrade06 --force
-----
+
In the unlikely event this step fails, please 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:

. Locate the +upgrade06.xsl+ conversion script provided with the source code
  (the https://github.com/ClusterLabs/pacemaker/tree/master/xml/upgrade06.xsl[latest version] is available via
  git).
          
. Convert the XML blob: indexterm:[XML,Convert]
+
-----
# 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]
+
----
# 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.
