In CFEngine you mainly interact with the CFEngine Hub, for example using the Mission Portal Web UI, APIs, ssh, or git. All other hosts in your infrastructure will communicate with the hub, to fetch policy, modules and data, and to send back reporting data. For you, this means that the experience of working with just 1 host, or 1000 hosts, is largely the same. So, the only thing you need to get started is to set up 1 CFEngine Hub.
There is a video version of this tutorial available on YouTube:
Linux virtual machine
CFEngine runs on a wide variety of platforms, including Windows, Mac, Linux, and BSD. For this tutorial, to make things simple, we are going to recommend one way to install and work with CFEngine. We will use an Ubuntu 20.04 Linux virtual machine as the CFEngine Hub, and we will interact with it using SSH and some python tools which you can install on your desktop / laptop.
If you've never set up a virtual machine (VM) before, these are some easy ways:
- Cloud: Create a VM in Digital Ocean, AWS, or any other cloud vendor. (Recommended)
- Mac OS: Install and run Vagrant and Virtual Box.
- Linux: Install and run Vagrant and libvirt.
- Windows: Use Windows Subsystem for Linux (WSL).
We recommend using Digital Ocean because it is very easy to use the GUI, and spawn a virtual without installing something locally. However, since it requires you to create an account, some users might prefer to install virtualization software and run everything themself. This is also possible, for example using Vagrant and VirtualBox, and we will provide instructions for both.
Development machine and CFEngine Hub
With the Linux VM there are 2 machines we will be talking about:
The CFEngine hub is the aforementioned Ubuntu 20.04 VM. We will access this via SSH, and install CFEngine there.
Your development machine is the machine you have in front of you, it can be any platform (Linux, Mac, Windows, ...). This is where you will run a terminal, browser, text editor, and some python tools. Throughout this tutorial we will tell you various commands to run on the command line (terminal), like this:
Feel free to use the copy to clipboard button and paste it into your terminal, or type it in.
Install python 3 on your development machine
Install brew from brew.sh. Use brew to install Python 3:
brew install python3
sudo apt-get install python3 python3-pip
If you are using Windows and Ubuntu inside of WSL, the command is the same.
Not all systems use
apt-get as the package manager - if you are not using Ubuntu, look up how to install python 3 and pip on your system.
Check that it was successful:
To continue, you will need to be able to use
And similar for
pip 22.3 from /usr/local/lib/python3.10/site-packages/pip (python 3.10)
The python version must be at least 3.6, and it's important that the pip output shows a matching python version (otherwise pip is using another installation of python).
Install CFEngine tools on your development machine
In this tutorial series, we will be using 2 command line tools:
These are small python tools and don't make changes to your system, they are only for working with CFEngine projects, modules, and installing / deploying to remote machines.
Depending on your operating system and how you installed python, you may be able to install python tools without
This is common on macOS:
pip3 install cfbs cf-remote
However, on other systems, notably popular Linux distributions, it is common to require root privileges (or extra configuration) to install python packages:
sudo pip3 install cfbs cf-remote
There are many ways to install command line tools with
pip, if you want to do it without
sudo, and install it in your home directory, and edit the
PATH variable, or if you want to use virtual environments, you can.
The commands above are suggestions which should work for most people.
Importantly, you need the command line tools working after you've installed them:
Just as above, with python, you should see the version number like this:
And similarly for
cf-remote version 0.4.5 Available CFEngine versions: master, 3.20.0, 3.18.x, 3.18.2, 3.18.1, 3.18.0, 3.15.x, 3.15.6, 3.15.5, 3.15.4, 3.15.3, 3.15.2, 3.15.1, 3.15.0, 3.15.0b1
Virtual Machine IP and username
Decide on whether you want to use VMs in the cloud (Digital Ocean) or locally (Vagrant and Virtual Box) and follow the appropriate instructions below.
Using Digital Ocean / Cloud platforms:
Spawn an Ubuntu 20.04 Linux Virtual Machine using the web GUI.
Find the IP address of your virtual machine, and the username so you can log in with SSH.
For example, in Digital Ocean, the username is
root, and the IP might be
184.108.40.206 (found in top left of droplet screen as "ipv4"):
Note: In the rest of this tutorial, replace the IP address we use in the examples,
192.168.56.2 with that IP.
Using Vagrant and Virtualbox:
Come back to this tutorial after you have completed the installation and setup of a VM as explained in this tutorial:
Connecting with SSH
On your development machine:
Test that ssh works:
ssh firstname.lastname@example.org -C "echo hello"
If you see
hello printed, it worked! If not, these are some of the more common error scenarios:
- If it prints
Connection refused, it might be because you just started the machine, wait a bit and try again.
- If it hangs for many seconds, it might mean that you typed the wrong IP address (
Ctrl + Cto interrupt).
- If it prints
Connection timed out, you are most likely using the wrong IP address.
- If it gives any other errors, such as
Permission denied (publickey)you may be using the wrong user / SSH key or IP address. Double check and try again.
After you see ssh working, save the host in
cf-remote so you can copy-paste our later commands:
cf-remote save -H email@example.com --role hub --name hub
Note: If you are not using the vagrant machine with that IP address, remember to replace it with the one you use.
The host is now in a
cf-remote group called
hub, so we don't have to type the username and IP, for example:
cf-remote info -H hub
firstname.lastname@example.org OS : Ubuntu 20 Architecture : x86_64 CFEngine : Not installed Policy server : None Binaries : dpkg, apt
The output shows you the information needed for SSH (username and hostname / IP) as well as some key information about the host, such as architecture and operating system:
From your development machine, use
cf-remote to install CFEngine on the Linux VM:
cf-remote install --hub hub --bootstrap hub
CFEngine is now installed and running on your hub, including the Web UI, the reporting database, and the components responsible for making changes to your system, serving and fetching policy, etc.
Open the CFEngine Web UI
Open the CFEngine Web UI in a web browser by clicking this link, or typing the appropriate IP in the address bar:
You might get warnings about an insecure connection or invalid certificate.
At this point, your hub has a self signed certificate, which means there is no certificate authority that can verify which server you are talking to.
In the future you might want to set up a DNS entry for your hub and give it a proper certificate, but for now, you can click the options in your browser to Ignore / Continue.
(In Chrome, there might not be an "Accept and continue button", but you can type
thisisunsafe to bypass the security warning).
After this, you should see the CFEngine Enterprise login screen. Log in with username admin, password admin, and you will be asked to change the password.
After changing the password to something more secure, you should be able to log in and see the dashboard.
Now that you have a CFEngine Hub working and the tooling on your development machine, you can go to the next part and start adding modules: