Get Started Guide for CFEngine 3 Nova

Igniting CFEngine 3 Nova!

COMPLETE TABLE OF CONTENTS

Summary of contents

• Installing CFEngine 3 Nova
• Mission Portal
• Next steps

1 Installing CFEngine 3 Nova

• Installation procedure

1.1 Installation procedure

CFEngine 3 Nova is designed to be simple to install in its default configuration. The installation process has three phases:

• Unpacking the software.
• Obtaining a license.
• Adapting policy.

For Windows related issues, see our special topic guide http://cfengine.com/manuals/st-windows.html.

You should start from a blank system. If you have been using CFEngine Community Edition and you have already developed a policy, set aside this policy during the installation process. You will be able to integrate it back later.

Nova is provided in two packages, cfengine-nova and cfengine-nova-expansion. The main software package must be installed on every host (including the hub). The expansion package is only installed on the policy hub. You should install and set up the hub first.

1. Verify that the machine's network connection is working. On the hub, verify that package managers yum, zypper or apt-get are working (e.g. apt-get update).
2. Copy the Nova packages to the system. On the hub (policy server):

             cfengine-nova_2.1.xxx.[rpm|deb]
             cfengine-nova-expansion_2.1.xxx.[rpm|deb]
   

   On all other machines:

             cfengine-nova_2.1.xxx.[rpm|deb]
   

3. Unpack the software:

   Red Hat family

                  host# rpm -ihv packages
   

   
   

   SUSE family

                  host# rpm -ihv packages
   

   
   

   Debian family

                  host# dpkg --install  packages
   

4. On the hub, a public key has now been created in /var/cfengine/ppkeys/localhost.pub as part of the package installation. You should send this public key to CFEngine Support¹ as an attachment in the ticket system, to obtain a license file license.dat.

   Save the returned license file to /var/cfengine/masterfiles/license.dat on the hub before continuing.

5. The remaining steps apply to all hosts, but you should install the hub or policy server first. For large systems (> 1000 hosts) we recommend increasing the memory limit in php.ini on the hub (for instance to 128 MB).

   Find the hostname or IP address of the hub (policy server), here we assume ‘123.456.789.123’ is the address.

         hub # /var/cfengine/bin/cf-agent --bootstrap --policy-server 123.456.789.123
   

   Use the same command on all hosts, i.e. *** do not bootstrap the policy server with a localhost address *** If you mistype the address of the hub, we recommend doing the following steps to re-boostrap.

         hub # /var/cfengine/bin/cf-agent --bootstrap --policy-server 123.456.789.124
         hub # killall cf-execd cf-serverd cf-monitord cf-hub
         hub # rm -rf /var/cfengine/inputs/*
         hub # rm -f /var/cfengine/policy_server.dat
         hub # /var/cfengine/bin/cf-agent --bootstrap --policy-server 123.456.789.123
   

   CFEngine will output diagnostic information upon bootstrap. Error messages will be displayed if bootstrapping failed, pursue these to get an indication of what went wrong and correct accordingly. If all is well you should see the following in the output:

        
        -> Bootstrap to 123.456.789.123 completed successfully
        
   

6. CFEngine should now be up and running on your system. It will copy its default policy files into masterfiles on the hub (policy server). When the clients are bootstrapped, they will contact the hub and copy them to their inputs directory.
7. To complete licensing setup, you should make a promise to accept the license terms by editing /var/cfengine/masterfiles/promises.cf on the hub (policy server), changing the line ‘host_licenses_paid => "<NUMBER>";’ in ‘body common control’ to reflect the correct number of licenses that you have subscribed to.

How to assess success in this procedure:

1. Look at the process list on the systems with ‘ps waux | grep cf-’. You should be able to see cf-execd running, and eventually other processes from the CFEngine suite like cf-monitord cf-serverd. On the hub, you should also eventually see cf-hub. Note that it may take 5–10 minutes before all the processes get started.
2. Look for files in /var/cfengine/inputs (Unix) or C:\Program Files\Cfengine\inputs (Windows). The license file will be copied out from the policy server to the clients as part of the normal distribution of policy. Each machine should get a copy of the license.dat file in /var/cfengine/inputs (Unix) or C:\Program Files\Cfengine\inputs (Windows).
3. On the hub, the file /var/cfengine/promise_knowledge.cf should have been created, and should contain data.
4. Finally, try to connect to the web server at port 80 on the hub/policy host (for example at http://123.456.789.123). You should see a login page like the one shown in the figure below:
   
   Figure: Mission Portal login screen

Default user name and password is 'admin' and 'admin' (make sure to change this at first login to prevent unauthorized access).

Note that some of the displays in the Mission Portal may be blank when you log in just after installation; some reports and graphs are only updated every six hours. It may also take some time for the system to fully converge, do not get troubled if initially there are some promises repaired or not kept.

Please refer to the CFEngine 3 Nova Owner's Manual
(http://www.cfengine.com/manuals/NovaOwnersManual.html) for complete information and help troubleshooting your installation.

2 Mission Portal

• Mission Portal Rooms

The Mission Portal is the centerpiece of user interaction with CFEngine 3 Nova. It can be accessed by connecting to the hub (policy server) with your web browser (for example at http://123.456.789.123; default port 80). From here you can get a complete overview of operations and performance, business and compliance, organizational knowledge and library. We will make a quick introduction of the four main rooms in the Mission Portal, please refer to the CFEngine 3 Nova Owner's Manual for a complete overview: http://www.cfengine.com/manuals/NovaOwnersManual.html

2.1 Mission Portal Rooms

• Mission Status
• Mission Engineering
• Mission Planning
• Mission Library

There are four main rooms in the Mission Portal that offer insight into different aspects of operations:

• Mission status: a top level overview of compliance status and business value
• Mission engineering: a place to see the current state of system repair
• Mission planning: a place to plan and make policy changes
• Mission library: a knowledge bank that connects information together

Each of these rooms is a beginning from which you can refine your overview and search through information.

2.1.1 Mission Status

Mission status is a high level summary of how well the entire system is behaving.

Compliance Summary: The row of bar meters shows the compliance (average percentage of promises kept, repaired or not kept) of all registered hosts ² in blocks of 6 hours for the past week. It summarizes performance and anomalous behavior in a simple red (promises not kept), yellow (promises repaired) and green (promises kept) scale. Click on a bar to see which promises were kept/not kept.

Services/Goals: A summary of Mission goals (as defined in user policy files). See the CFEngine 3 Nova Owners Manual for more information.

2.1.2 Mission Engineering

Mission engineering illustrates the state of the system in relation to the desired state at all scales. Zoom in to specific areas and examine the impact of promises, query data, and extract reports.

• The hosts are classified into red, yellow, green and blue according to the status of their compliance. A host is red if less than 80% of its promises are kept (> 20% not compliant), yellow if 20% or more of its promises were repaired and host is now compliant (> 20% repaired, now compliant), green if more than 80% of its promises are kept (> 80% compliant), and blue if there is no contact between the hub and the client (host unreachable). Clicking a link produces a list of the hosts in that category.
• Worst available host rank: Display the weakest hosts (that have been in contact with the hub) over the last hour.
• Hub replication status: Display status of redundant monitoring hubs (if activated).

Promise compliance summary for reachable hosts:
The row of bar meters shows the compliance (average percentage of promises kept, repaired or not kept) of all registered hosts over the past week, the past day and the past hour. It summarizes performance and anomalous behavior in a simple red (promises not kept), yellow (promises repaired), and green (promises kept) scale. The "Chng" bar relates to the amount of changes made to files monitored by a CFEngine policy in the last hour (change watch). It is green if no changes have been made. The level of yellow increases as changes occur (but it will never be red). For the "Seen" bar, CFEngine monitors connections to the clients and reports a yellow or red status according to the length of time since it was in touch with one of the managed clients. The "Anom" bar relates to anomalies and is generated from monitoring data (vitals) for the last week.

Finders: The Mission Engineering room comes with six finder functions (modules that make it simple and intuitive to browse and search for objects of a particular type): host, class, promises, reports, summary reports, and CDP (Content Driven Policies) reports. See CFEngine Owner's Manual for more information.

2.1.3 Mission Planning

Make changes to policies, goals determined by promises and implement specific tactics to achieve the desired state. Interact with data, approve changes and anomalies. Get an overview of users logged on to the Mission Portal, as well as their current activity.

Action buttons:

• Repository: Edit policy files in the integrated policy editor (requires Subversion)
• Track records: Overview of promises repaired or not kept
• Approve policies: Give your approval of a submitted policy file
• Service catalogue: See which bundles contribute to policy goals

Logged on: Shows users currently logged on to the Mission Portal and their activity.

Activity log: Shows the latest activity entries. Type in a new activity to keep colleagues posted on current work.

2.1.4 Mission Library

• Topics viewer (Knowledge map)

• Docs: Overview of documentation that was packaged with CFEngine 3 Nova.
• Find Topic: Search for topics either by scrolling through the alphabetical list or by typing in the search box (same as the search box on top right of page).
• Notes Archive: Get overview of all notes made in regard to hosts or reports.
• Community: External link to the CFEngine community

2.1.4.1 Topics viewer (Knowledge map)

The Topics viewer, or Knowledge map, is a sematic web of subject references and document pointers. In a semantic web, you are presented with links to documents about your chosen topic. In addition you are offered leads and possible pathways to topics that are known to be related. These leads don't just point you to more documents, but explain how neighboring issues are related. The aim is to help the user learn from the experience of browsing, by conveying the meaning of the current topic in relation to other issues in the system. This is how knowledge transfer occurs.

The Knowledge Map can be found by searching for a topic in the top right corner or through the topic finder in the Mission Library (this will sometimes also lead directly to a document or web page instead).

3 Next steps

Please refer to the CFEngine 3 Nova Owner's Manual for complete information about this product. You may also wish to visit our getting started section on cfengine.com:

• http://cfengine.com/manuals/NovaOwnersManual.html
• http://cfengine.com/getting-started