Upgrading
This guide documents our recommendation on how to upgrade an existing installation of CFEngine Enterprise to 3.12. 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.
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:
root@hub:~# systemctl stop cfengine3
For SysVinit:
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.
root@hub:~# tar -czf /tmp/$(date +%Y-%m-%d)-cfengine-full-backup.tar.gz /var/cfengine /opt/cfengine
See Also: Hub administration backup and restore
Copy the archive to a safe location.
Start the CFEngine services.
For systemd managed systems:
root@hub:~# systemctl start cfengine3
For SysVinit:
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
.
Once the Masterfiles Policy Framework has been qualified and distributed to all agents you are ready to begin binary upgrades.
Enterprise Hub binary upgrade
Ensure the CFEngine services are running
For systemd managed systems:
root@hub:~# systemctl start cfengine3
For SysVinit:
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 exportingBACKUP_DIR
before package upgrade.Red Hat/CentOS:
root@hub:~# export BACKUP_DIR="/mnt/plenty-of-free-space" root@hub:~# rpm -U cfengine-nova-hub-3.12.7-1.el6.x86_64.rpm
Debian/Ubuntu:
root@hub:~# export BACKUP_DIR="/mnt/plenty-of-free-space" root@hub:~# dpkg --install cfengine-nova-hub_3.12.7-1_amd64-deb7.deb
Community does not have a hub specific package.
Check
/var/log/CFEngineHub-Install.log
for errors.Run the policy on the hub several times or wait for the system to converge.
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 thecfengine_master_software_content_state_present
class defined.For example:
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.{ "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
-
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":"3.12.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.