Take the Plunge! Upgrading to CFEngine 3.6.1

We recently announced the general availability of CFEngine Enterprise 3.6.1. One of the key capabilities added to this maintenance release is a supported upgrade process. In today’s post, I’ll walk you through an outline of the upgrade procedure, which will hopefully provide a good starting point for you to map out the entire process for your CFEngine deployment. Note that the examples here assume starting the upgrade from a CFEngine 3.5.x install, but the same steps are applicable to version 3.0 as well. Don’t forget to refer to our online documentation for the complete set of steps.

How should you begin?

Start with the Policy Server. Keep in mind that the agents are autonomous, so even as the Policy Server is taken down or disconnected from the hosts that it is managing, it will still be “business as usual” for the hosts, as they will continue to be governed by their existing set of policies.

Back up your Policy Server

Prior to performing any upgrade, you should back everything up in your current install (e.g. /var/cfengine). As an example, tar everything up in a CFEngine 3.5 deployment to a local directory like /root/3.5:

$ mkdir -p /root/3.5
$ tar cvzf /root/3.5/cfengine.tar.gz /var/cfengine

You may also wish to make a copy of your ppkeys as well as a list of the hosts connected to this Policy Server so you can easily look them up should you need them later.

$ cp -r /var/cfengine/ppkeys /root/3.5/ppkeys
$ cf-key -s > /root/3.5/hosts

Prep your Policy Server for the upgrade

There are a few things that need to be done prior to stopping the CFEngine processes on the Policy Server.

Merge your existing policies and masterfiles into CFEngine 3.6

This is going to be the most time consuming step as you will be merging all the policy bundles you have in your existing install into the CFEngine 3.6 version of the masterfiles. I recommend finding a separate machine on which you can perform a vanilla install of CFEngine 3.6.1. This way, you will be able to obtain pristine copies of the CFEngine 3.6 masterfiles from which you can start the merge process. Since you don’t want to corrupt your existing CFEngine 3.5 environment, save the merged masterfiles into a directory location that is readily available, such as /root/3.6/masterfiles. You will be copying these files over to your upgraded Policy Server later. Since you have likely made a number of edits while merging the masterfiles, it’s best to run them through cf-promises to ensure that they are well formed and will execute successfully in your existing environment, as well as in the upgraded CFEngine 3.6 environment.

$ cf-promises -cf /var/cfengine/masterfiles/update.cf
$ cf-promises -cf /var/cfengine/masterfiles/promises.cf

If there is no resulting output from cf-promises, then you are all set to continue with the upgrade. Otherwise, you should fix any reported issues in your policies.

Set update_policy.cf

Open up the 3.6 version of update_policy.cf and set trustkeysfrom to trust all hosts. Without this setting, the hosts will not trust the IP address of the policy server once it has been upgraded to CFEngine 3.6.

Export data from MongoDB (applicable to enterprise version installs only)

If you are an enterprise customer, we’ve provided a utility called cfmigrate to help you export data from the previous MongoDB datastore. The data exported include users and role settings, as well as file-changes data. You can download a copy of cfmigrate from here. Once you have downloaded this handy utility onto the Policy Server, give it executable permissions and perform an export.

$ chmod +x cfmigrate
$ ./cfmigrate export

By default, cfmigrate writes out data files extracted from MongoDB to the local directory. Towards the end of the Policy Server upgrade procedure, you will be executing cfmigrate again to import these data files into PostgreSQL. To see additional options for executing this utility, please refer to the help by issuing the following command:

$ ./cfmigrate export -h

Upgrade the Policy Server

You are now ready to perform the actual upgrade of the Policy Server. This involves shutting down the existing CFEngine services, removing the existing instance, installing the new packages, and copying over the merged masterfiles. The documentation provides all of these steps, but I will repeat them here for your convenience.

Stop CFEngine Services
```
$ service cfengine3 stop
```

Uninstall the previous CFEngine Policy Server package

$ rpm -e cfengine-nova-hub # Red Hat based distribution
$ dpkg -p cfengine-nova-hub # Debian based distribution
$ rm -rf /var/cfengine

Install the new CFEngine Policy Server package. Click here to download the latest versions.

$ rpm -i cfengine-nova-hub-3.6.1-1.x86_64.rpm # Red Hat based distribution
$ dpkg --install cfengine-nova-hub_3.6.1-1_amd64.deb # Debian based distribution

Restore ppkeys from your backup

$ cp /root/3.5/ppkeys/* /var/cfengine/ppkeys/

Restore your Enterprise license file into /var/cfengine/masterfiles/license.dat

Remove the out-of-the-box masterfiles and replace them with your copy the merged masterfiles

$ rm -rf /var/cfengine/masterfiles/*
$ cp /root/3.6/masterfiles/* /var/cfengine/masterfiles/

Bootstrap the Policy Server to itself

$ /var/cfengine/bin/cf-agent -B [Policy Server IP Address]

Import your enterprise data from MongoDB to PostgreSQL (applicable to enterprise version installs only)
```
$ ./cfmigrate import
```
To see additional options for running cfmigrate, please refer to ./cfmigrate import -h
Verify that users can log in to the Mission Portal
Take the Policy Server online and verify that some clients have received the updated policies and can execute them without error

Upgrade the Clients

Now that you have successfully upgraded the Policy Server, you can now shift your focus to the clients. This one should be pretty straightforward. Download the relevant client packages onto the Policy Server, and then place them in /var/cfengine/master_software_updates/ under the appropriate subdirectory for the operating systems of your hosts. When the client “phones home” to the Policy Server, they will find these updated packages to perform a “self-upgrade”. Note that you might also wish to take an iterative approach and limit the upgrade to a small subset of clients at a time. You can do this by setting the trigger_update class in update.cf to a subset of host IP addresses. Since you had previously set trustkeysfrom at the start of this entire process, you can now revert this back to its previous configuration in update.cf after the clients have been upgraded and are connected to the Policy Server. As the clients get upgraded, make sure that they appear in the Mission Portal if you are a user of the enterprise version. And there you have it! You have now successfully upgraded and are running our latest release, CFEngine 3.6.1!