Change in behavior: self upgrade now defaults to hub binary version

Posted by Nick Anderson
November 15, 2023

In the upcoming release of 3.23.0, there is a change in behavior with respect to the self upgrade policy. Beginning with 3.23.0 the self upgrade policy will default to the binary version that is running on the hub instead of the version of the policy framework that is executing.

When upgrading CFEngine1 there are three major steps:

  • Upgrade the Masterfiles Policy Framework (MPF)
  • Upgrade the hub binaries
  • Upgrade the client binaries

Generally it’s desirable that the MPF version is equal to or greater than the hub binary version and the hub binary version is equal to or greater than the client binary version. This way the policy has necessary knowledge in place prior to a binary upgrade where behavior may change.

Previously the MPF defaulted the self upgrade desired binary version to the version of the policy. If hosts are configured to self update when a new policy was released this could result in clients upgrading to a newer binary version before the hubs binary version is upgraded. While this is not typically problematic, we thought that defaulting to the hubs current binary version was better aligned with the recommended configuration.

As before you can specify the desired binary version by defining default:def.cfengine_software_pkg_version 2 via Augments.

For example:

    "classes": {
        "default:trigger_upgrade": {
            "class_expressions": [ "!(am_policy_hub|policy_server).!cfengine_3_21_3::" ],
            "comment": "We want clients to self upgrade their binary version if they aren't running the desired version."
    "variables": {
        "default:def.cfengine_software_pkg_version": {
            "value": "3.21.3",
            "comment": "When self upgrading, this is the binary version we want to be installed."

To facilitate this change as part of the update policy entry (, the hub now maintains $(sys.statedir)/cf_version.txt containing the its current binary version in the form $(sys.cf_version_major).$(sys.cf_version_minor).$(sys.cf_version_patch)-$(sys.cf_version_release). It’s accessible to hosts described by def.acl and has a shortcut hub-cf_version. Clients maintain a copy of the hubs binary version as $(sys.statedir)/hub_cf_version.txt and the self upgrade policy entry ( uses the content of this file for determining the desired binary version.

In summary, beginning with 3.23.0 if the self upgrade policy is active clients will default to the binary version that the hub is currently running. When the hubs binary version changes, clients will automatically start targeting the new binary version by default.

Get in touch with us
to discuss how we can help!
Contact us
Sign up for
our newsletter
By signing up, you agree to your email address being stored and used to receive newsletters about CFEngine. We use tracking in our newsletter emails to improve our marketing content.