Upgrading

Table of contents

This guide documents our recommendation on how to upgrade an existing installation of CFEngine Enterprise to master. Community users can use these instructions as a guide skipping the parts that are not relevant.

In short, the steps are:

Notes:

Upgrades are supported from any currently supported version.
Clients should not run newer versions of binaries than the hub. While it may work in many cases, Enterprise reporting does not currently guarantee forward compatibility. For example, a host running 3.15.0 will not be able to report to a hub running 3.12.3.
Masterfiles Policy Framework (MPF) should always be newer than or equal to your newest binary version. While things often work without performing the MPF upgrade you may miss important changes where the policy has been instrumented to account for changes in binary behavior. For example, if you upgraded to 3.18.2 or later without upgrading your policy framework you would see many warnings that the framework upgrade would have suppressed. That specific change was detailed in this blog post about changes in behavior to directory permissions and the execute bit.

Backup

Backups are made during the hub package upgrade, but it's prudent to take a full backup from your policy hub before making any changes so that you can recover if anything goes wrong.

Stop the CFEngine services.

For systemd managed systems:

 code
root@hub:~# systemctl stop cfengine3

For SysVinit:

 code
root@hub:~# service cfengine3 stop

Create an archive containing all CFEngine information.

Ensure you have enough disk space where your backup archive will be created.

 code
root@hub:~# tar -czf /tmp/$(date +%Y-%m-%d)-cfengine-full-backup.tar.gz /var/cfengine /opt/cfengine

For systemd managed systems:

 code
root@hub:~# find /usr/lib/systemd -name 'cf-*' -o -name 'cfengine*' | tar cfz /tmp/$(date +%Y-%m-%d)-cfengine-systemd-backup.tar.gz -T -

For SysVinit:

 code
root@hub:~# find /etc -name 'cfengine*' | tar cfz /tmp/$(date +%Y-%m-%d)-cfengine-init-backup.tar.gz -T -

Copy the archive to a safe location.

Start the CFEngine services.

For systemd managed systems:

 code
root@hub:~# systemctl start cfengine3

For SysVinit:

 code
root@hub:~# service cfengine3 start

Masterfiles Policy Framework upgrade

The Masterfiles Policy Framework is available in the hub package, separately on the download page, or directly from the masterfiles repository on github.

Normally most files can be replaced with new ones, files that typically contain user modifications include promises.cf, controls/*.cf, and services/main.cf.

Masterfiles Policy Framework upgrade Tutorial

Once the Masterfiles Policy Framework has been qualified and distributed to all agents you are ready to begin binary upgrades.

Enterprise hub binary upgrade

Note: Enterprise Hub packages want at least as much free space in the backup directory (/var/cfengine/state/pg/backup by default) as what is currently consumed in /var/cfengine/state/pg/data. Also, the backup directory should be empty before performing an Enterprise Hub binary upgrade.

Ensure the CFEngine services are running

For systemd managed systems:
code
```
root@hub:~# systemctl start cfengine3
```
For SysVinit:
code
```
root@hub:~# service cfengine3 start
```
Install the new Enterprise Hub package (you may need to adjust the package name based on CFEngine edition, version and distribution). By default, backups made during upgrade are placed in /var/cfengine/state/pg/backup, this can be overridden by exporting BACKUP_DIR before package upgrade.

NOTE: BACKUP_DIR should not exist and should be removable (e.g. it should not be a direct mount point).

Red Hat/CentOS:
code
```
root@hub:~# export BACKUP_DIR="/mnt/plenty-of-free-space"
root@hub:~# rpm -U cfengine-nova-hub-master.0-1a.el6.x86_64.rpm
```
Debian/Ubuntu:
code
```
root@hub:~# export BACKUP_DIR="/mnt/plenty-of-free-space"
root@hub:~# dpkg --install cfengine-nova-hub_master.0-1a_amd64-deb7.deb
```
Community does not have a hub specific package.
Check /var/log/CFEngine-Install.log for errors.

Run the policy on the hub several times or wait for the system to converge.

 code
root@hub:~# for i in 1 2 3; do /var/cfengine/bin/cf-agent -KIf update.cf; /var/cfengine/bin/cf-agent -KI; done

Agent binary upgrade

Publish binary packages under /var/cfengine/master_software_updates/$(sys.flavor)_$(sys.arch)/ on the policy server. To automatically download packages for all supported platforms execute the self upgrade policy with the cfengine_master_software_content_state_present class defined.

For example:
code
```
root@hub:~# cf-agent -KIf standalone_self_upgrade.cf --define cfengine_master_software_content_state_present
```
Define the trigger_upgrade class to allow hosts to attempt self upgrade. In this example hosts with IPv4 addresses in 192.0.2.0/24 or 203.0.113.0/24 network range, or hosts running CFEngine 3.10.x except for CFEngine 3.10.2. It's recommended to start with a small scope, and gradually increase until all hosts are upgraded.
code
```
{
  "classes": {
   "trigger_upgrade": [
     "ipv4_192_0_2",
     "ipv4_203_0_13",
     "cfengine_3_10_(?!2$)\d+"
   ]
  }
}
```
Note: The negative look ahead regular expression is useful because it automatically turns off on hosts after they reach the target version.
Verify that the selected hosts are upgrading successfully.

Mission Portal Inventory reporting interface

Inventory API

 code
 root@hub:~# curl -k \
 --user <admin>:<password> \
 -X POST \
 https://hub.localdomain/api/inventory  \
 -H 'content-type: application/json' \
 -d '{
       "sort":"Host name",
       "filter":{
          "CFEngine version":{
             "not_match":"master.0"
          }
       },
       "select":[
          "Host name",
          "CFEngine version"
        ]
     }'

Once all hosts have been upgraded ensure the trigger_upgrade class is no longer defined so that agents stop trying to self upgrade.

Upgrading

Backup

Masterfiles Policy Framework upgrade

Enterprise hub binary upgrade

Agent binary upgrade

Still need help?