D.2. Upgrading the Configuration

Pacemaker’s configuration — the Configuration Information Base (CIB) — has its own XML schema version, independent of the Pacemaker software version.

After cluster software is upgraded, the cluster will continue to use the older schema version that it was previously using. This can be useful, for example, when administrators have written tools that modify the configuration, and are based on the older syntax.

However, when using an older syntax, new features may be unavailable, 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 a good idea to follow the upgrade procedure outlined below, except for the last step, to ensure that the new software has no problems with your existing configuration (since it will perform much the same task internally).

If you are brave, it is sufficient simply to run cibadmin --upgrade.

A more cautious approach would proceed like this:

Create a shadow copy of the configuration. The later commands will automatically operate on this copy, rather than the live configuration.
```
# crm_shadow --create shadow
```
Verify the configuration is valid with the new software (which may be stricter about syntax mistakes, or may have dropped support for deprecated features):
```
# crm_verify --live-check
```
Fix any errors or warnings.
Perform the upgrade:
```
# cibadmin --upgrade
```
If this step fails, there are three main possibilities:
1. The configuration was not valid to start with (did you do steps 2 and 3?).
2. The transformation failed - report a bug or email the project.
3. The transformation was successful but produced an invalid result.
  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 Validation FAQ wiki page and/or try the manual upgrade procedure described below.
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:
```
# 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 shadow.dot -S
# graphviz shadow.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 Section 2.5, “Testing Your Configuration Changes” for further details on how to interpret the output of crm_simulate and graphviz.
Upload the changes:
```
# crm_shadow --commit shadow --force
```
In the unlikely event this step fails, please report a bug.

Note

It is also possible to perform the configuration upgrade steps manually:

Locate the upgrade*.xsl conversion scripts provided with the source code. These will often be installed in a location such as /usr/share/pacemaker, or may be obtained from the source repository.
Run the conversion scripts that apply to your older version, for example:
```
# xsltproc /path/to/upgrade06.xsl config06.xml > config10.xml
```
Locate the pacemaker.rng script (from the same location as the xsl files).

Check the XML validity:

# 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 are often more informative.