Supplement to CFEngine 3 Nova Evaluation Guide


Next: , Previous: (dir), Up: (dir)

Supplement to CFEngine 3 Nova Evaluation Guide

Table of Contents


Next: , Previous: Top, Up: Top

1 Standard reports in CFEngine 3 Nova

Standard reports in CFEngine 3 Nova can be accessed through the ‘Reports finder’ in the ‘Engineering’ room. The finder lists all standard report categories and each category contains information about different aspects of the Mission. When you click one of them, the ‘Report finder’ will present a query form that is adapted to the chosen report category. CFEngine uses regular expressions in these queries, for maximum flexibility and to minimize system impact. The details of these queries and the content of the resulting reports are outlined in the following sections.


Next: , Previous: Standard reports in CFEngine 3 Nova, Up: Standard reports in CFEngine 3 Nova

1.1 Bundle profile report

Promises are the fundamental statements in CFEngine, they make up the definition of the desired state of a system. A bundle is a collection of promises in a `sub-routine-like' container. The purpose of bundles is to allow greater flexibility to break down the contents of policies and give them names. Bundles also allow to re-use promise code by parameterizing it.

The ‘Bundle profile report’ is useful for checking when specific bundles were last verified and for seeing statistics about the frequency of verification. Click on Bundle profile in the ‘Reports finder’ to open a query window:


Go to bundle profile query
Figure: Go to Bundle profile query

The Bundle profile query can filter by bundle pattern (pattern in bundle name) and host class (i.e. the class/context of a bundle). Leaving the fields blank will result in a report listing all bundles in your policies.

Bundle profile query
Figure: Bundle profile query

Once you have clicked Generate report, CFEngine 3 Nova will list an overview of bundles that suit the query criteria entered above. It displays the host names on which these bundles can be found (‘Host’), the name of the bundles (‘Bundle’), the time stamp at the moment of verification (‘Last verified’), the time passed since last verification (‘Hours ago’), the average time between each verification (‘Avg interval’), and the uncertainty of that average (‘Uncertainty’, measured in one standard deviation of ‘Avg interval’). You can add your personal note in the right column, documenting any thoughts or issues that you might have about the query result. The ‘Last verified’ value is yellow if more than six hours have passed since last verification.

Bundle profile report
Figure: Bundle profile report


Next: , Previous: Bundle profile report, Up: Standard reports in CFEngine 3 Nova

1.2 Business value report

One of the capabilities of CFEngine 3 Nova is to add business or organizational value to the configuration model. The notion of business value is not necessarily a clear concept, but a simple approach is to attach a monetary value to the outcome of promises.

CFEngine's default values for promises kept, promises repaired and promises not kept are 1, 0.5, and -1, respectively. The values are summed and recorded at a set time interval, and the results are summarized for every host and day.

Click on Business value in the ‘Reports finder’ to open a query window:


Business value query
Figure: Business value query

The Business value query can filter by date and host class (i.e. the class/context of a host). Leaving the fields blank will result in a report listing the business value of all promises that have had value attached to them over all hosts and days.

Once you have clicked Generate report, CFEngine 3 Nova will list an overview of hosts that suit the query criteria entered above. The result presents each host name (‘Host’), date (‘Day’), and the sum of the value of the promises kept (‘Kept’), repaired (‘Repaired’), and not kept (‘Not kept’). You can add your personal note in the right column, documenting any thoughts or issues that you might have about the query result.


Business value report
Figure: Business value report


Next: , Previous: Business value report, Up: Standard reports in CFEngine 3 Nova

1.3 Class profile report

CFEngine classes are certain true/false (Boolean) propositions that determine in what context, or setting, a promise is made. Each time CFEngine runs (by default every five minutes), it discovers and classifies properties of the environment in which it runs. These discovered properties are called 'hard classes' and cannot be changed by users. CFEngine also operates with soft classes, i.e. user-defined types.

The Class profile report is useful for looking at hosts in specific contexts, for instance to find out which machines run on windows. Click on Class profile in the ‘Reports finder’ to open a query window:


Class profile query
Figure: Class profile query

The class profile query can filter by (pattern in) class name and host class (i.e. the context of a host). Leaving the fields blank will result in a report listing all hosts and classes.

Once you have clicked Generate report, CFEngine 3 Nova will list an overview of hosts that suit the query criteria entered above. The result presents the host names (‘Host’), ‘Class context’, probability of occurrence (‘Occurs with probability’), ‘Uncertainty’ (standard deviation of ‘Occurs with probability’), and the last time the class was observed (‘Last seen’).


Class profile report
Figure: Class profile report


Next: , Previous: Class profile report, Up: Standard reports in CFEngine 3 Nova

1.4 Compliance by promise report

Promises are the fundamental statements in CFEngine, the policy atoms. Promises can be made about all kinds of different subjects, from file attributes, to the execution of commands, access control decisions and knowledge relationships. If there is no promise, nothing happens. It is considered compliant if CFEngine is able to keep the promise, and conversely, not compliant, or not kept, in the opposite case.

The ‘Compliance by promise’ report is useful for checking the current status of your system in high detail. You can find out which parts of a bundle work and which do not. The report also predicts the probability of compliance based on the history of specific promises, allowing you to assess the degree to which the problem is of a more transient or permanent nature. Click on Compliance by promise in the ‘Reports finder’ to open a query window:


Compliance by promise query
Figure: Compliance by promise query

The compliance by promise query can filter by (patterns in) promise handle, any/compliant/repaired/non-compliant promises (drop-down menu), and host class (i.e. the context of a host). Leaving the fields blank will result in a report listing all hosts and and promises.

Once you have clicked Generate report, CFEngine 3 Nova will list an overview of hosts that suit the query criteria entered above. The result presents the host names (‘Host’), the promise identifier ‘Promise handle’, ‘Last known state’ (compliant or not compliant), likelihood of a promise being compliant (‘Probability kept’), uncertainty of the likelihood (‘Uncertainty’, measured in one standard deviation of ‘Probability kept’), and the time stamp of the last time the promise was run.


Compliance by promise report
Figure: Compliance by promise report


Next: , Previous: Compliance by promise report, Up: Standard reports in CFEngine 3 Nova

1.5 Compliance summary report

CFEngine policies are collections of promises contained in a text file, they are the CFEngine scripts that define what state you want your system to be in. The compliance summary report gives an overview of policy status. It shows the current status of your system in a coarse manner, allowing you to quickly identify which areas need follow-up. Click on Compliance summary in the ‘Reports finder’ to open a query window:


Compliance summary query
Figure: Compliance summary query

The compliance summary query can filter by (pattern in) promise handle and host class (i.e. the context of a host). Leaving the fields blank will result in a report listing all hosts and and policies.

Once you have clicked Generate report, CFEngine 3 Nova will list an overview of hosts that suit the query criteria entered above. The result presents the host names (‘Host’), policy file name (‘Policy’), percentage of promises kept within the listed policies (‘Kept’), percentage of promises repaired within the listed policies (‘Repaired’), percentage of promises not kept within the listed policies (‘Not kept’), and the time stamp of the last status check (‘Last seen’).


Compliance summary report
Figure: Compliance summary report


Next: , Previous: Compliance summary report, Up: Standard reports in CFEngine 3 Nova

1.6 File change log report

File change monitoring is about detecting when file information on a computer system changes. Awareness of changes is often considered a major part of management, especially if they are unexpected or inadvertent (expected changes are usually not a problem). With CFEngine you can either set a general tripwire to detect all changes, or, in the case of the ‘File change log’, monitor specific files with changes promises. The report gives you relative detail of change as it presents the name of files that have been changed, when they were changed and on what host they were changed.

The file change log query can filter by (patterns in) file name and host class (i.e. the class/context of a host). Leaving the fields blank will result in a report listing changes detected on all monitored hosts and and policies.


File change log query
Figure: File change log query

Once you have clicked Generate report, CFEngine 3 Nova will list an overview of hosts that suit the query criteria entered above. The result presents the host names (‘Host’), name of the file where a change was detected (‘File’), and time stamp of change detection (‘Change detected at’). You can add your personal note in the right column, documenting any thoughts or issues that you might have about the query result.

File change log report
Figure: File change log report


Next: , Previous: File change log report, Up: Standard reports in CFEngine 3 Nova

1.7 File change diffs report

A diff is a file comparison utility that outputs the differences between two files. It is typically used to show the changes between one version of a file and a former version of the same file. Diff displays the changes made per line for text files. Once a file change has been identified, for instance as seen in the file change log, you can browse the details of that change in a file change diff report.

The file change diff query can filter by (pattern in) file name, (pattern in) diff content, and host class (i.e. the class/context of a host). Leaving the fields blank will result in a report listing changes detected on all monitored hosts and and policies.


File change diffs query
Figure: File change diffs query

Once you have clicked Generate report, CFEngine 3 Nova will list an overview of hosts that suit the query criteria entered above. The result presents the host names (‘Host’), name of the file where a change was detected (‘File’), the time stamp of change detection (‘Change detected at’), and the actual diff (whether a line was added or deleted, the line number, and the content of the change; ‘Change added (+), deleted (-); Line no; Content ’).

File change diffs report
Figure: File change diffs report


Next: , Previous: File change diffs report, Up: Standard reports in CFEngine 3 Nova

1.8 Last saw hosts report

Sometimes it is not possible to connect to a machine under CFEngine's management, either due to network errors or temporary lack of network entirely (for instance on ships at sea or submarines). CFEngine 3 Nova's Mission Portal monitors all connections, incoming and outgoing, between all managed hosts, and creates a log of when neighboring hosts were last observed online. This information is used to set the host availability status and, through analysis of the connection history, give an idea of the regularity of connections between hosts.

The Last saw hosts report is useful for checking the communication pattern between managed hosts and when they last were in touch with each other. Click on Last saw hosts in the Report finder to open a query window as described previously.


Last saw hosts query
Figure: Last saw hosts query

The Last saw hosts query can filter by (patterns in) remote host name, remote host IP address, remote host key, minimum hours ago (since the last connection was made), and host class (i.e. the class/context of a host). Leaving the fields blank will result in a report listing all connections made to and from the managed machines (including the hub).

Once you have clicked Generate report, CFEngine 3 Nova will list an overview of all communication that suits the query criteria entered above. Every connection is logged on the concerned nodes as incoming (Initiated by them) or outgoing (Initiated by us), the same connection will therefore appear twice in the report (once for each node). The results are presented in the following column format: ‘Host’ (host name), ‘Initiated’ (identifies whether the connection is incoming (by them (-)) or outgoing (by us (+)), ‘Remote host name’, ‘Remote host IP address’, ‘Last seen’ (time stamp of the connection), ‘Hours ago’ (interval between current time and Last seen), ‘Avg interval’ (average time between each connection), ‘Uncertainty’ (standard deviation of Average interval), and ‘Remote host key’ (identifying key of the remote host).


Last saw hosts report
Figure: Last saw hosts report


Next: , Previous: Last saw hosts report, Up: Standard reports in CFEngine 3 Nova

1.9 Patches available report

Software packaging is a core paradigm in operating system release management today, and CFEngine supports a generic approach to integration with native operating support for packaging. Package promises allow CFEngine to make promises the state of software packages conditionally, given the assumption that a native package manager will perform the actual manipulations. Since no agent can make unconditional promises about another, this is the best that can be achieved.

Some package systems also support the idea of patches. These might be formally different objects to packages; a patch might contain material for several packages and be numbered differently. When you select patching-policy, the package name can be a regular expression that will match possible patch names, otherwise identifying specific patches can be cumbersome.

The patches available report is useful to get an overview of patches claimed to be available by the local package manager. Click on Patches available in the ‘Reports finder’ to open a query window:


Patches available query
Figure: Patches available query

The Patches available query can filter by (patterns in) package name, package version, package architecture, and host class. Leaving the fields blank will result in a report listing all patches that can be installed on the system.

Once you have clicked Generate report, CFEngine 3 Nova will list an overview of patches that suit the query criteria entered above. The report presents the following columns: ‘Host’ (host name), ‘Name’ (name of the package/patch), ‘Version’ (patch version), and ‘Architecture’.


Patches available report
Figure: Patches available report


Next: , Previous: Patches available report, Up: Standard reports in CFEngine 3 Nova

1.10 Patch status report

Patch management can be a delicate business: sometimes a patch can cause new problems, or perhaps even more problems than it fixes. IT managers therefore often like to be in control of what patches are applied to a system. The Patch status report gives system administrators a complete overview of applied patches according to the local package manager, and, in conjunction with the patches available report, allows them to consciously decide which patches to apply or not.

Click on Patch status in the ‘Reports finder’ to open a query window:


Patch status query
Figure: Patch status query

The Patch status query can filter by (patterns in) package name, package version, package architecture, and host class. Leaving the fields blank will result in a report listing all patches applied to the system.

Once you have clicked Generate report, CFEngine 3 Nova will list an overview of patches that suit the query criteria entered above. The report presents results in the same format as the Patches available report: ‘Host’ (host name), ‘Name’ (name of the package/patch), ‘Version’ (patch version), and ‘Architecture’.


Patch status report
Figure: Patch status report


Next: , Previous: Patch status report, Up: Standard reports in CFEngine 3 Nova

1.11 Performance report

CFEngine 3 Nova uses several monitoring probes to reflect on general system performance1. One probe looks at the time it takes to execute selected promises; results are summarized in the ‘Performance report’. The user can thus evaluate which parts of a policy put charge on the system in terms of time spent completing a task. Longer tasks, such as command execution and file copying, are measured by default, but other tasks have to be measured explicitly by stating so in a policy. Note however that most promises made in CFEngine are executed so fast we are not able to measure the time it takes to complete them.

Click on Performance in the ‘Reports finder’ to open a query window:


Performance query
Figure: Performance query

The Performance query can filter by (patterns in) job name and host class. Leaving the fields blank will result in a report listing the performance of all monitored jobs.

Once you have clicked Generate report, CFEngine 3 Nova will list an overview of events that suit the query criteria entered above. ‘Host’ (host name), ‘Event’ (job name), ‘Last time’ (most recent performance value, i.e. the time it took to complete the job), ‘Avg time’ (average of all Last time), ‘Uncertainty’ (expressed as one standard deviation of ‘Avg time’), and ‘Last performed’ (time stamp of last execution). You can add your personal note in the right column, documenting any thoughts or issues that you might have about the query result.


Performance report
Figure: Performance report


Next: , Previous: Performance report, Up: Standard reports in CFEngine 3 Nova

1.12 Promises repaired log report

The Status room in the Nova Mission Portal gives an overview of the general status of your system, including six hour summaries of promises kept, repaired, and not kept from the last week. The Promises repaired log is useful to get a complete overview of the history of promises repaired, including execution order and events that are more than a week old. Click on Promises repaired log in the ‘Reports finder’ to open a query window:


Promises repaired log query
Figure: Promises repaired log query

The Promise repaired log query can filter by (patterns in) promise handles, host class (i.e. the class/context of a host), and a desired time interval. Leaving the fields blank will result in a report listing all promises that were repaired and the time of occurrence.

Once you have clicked Generate report, CFEngine 3 Nova will list an overview of promises that suit the query criteria entered above. The results are presented as ‘Host’ (host name), ‘Promise handle’ (identifier of the promise), ‘Report’ (what was repaired), and ‘Time’ (time stamp of the repair action). You can add your personal note in the right column, documenting any thoughts or issues that you might have about the query result.


Promises repaired log report
Figure: Promises repaired log report


Next: , Previous: Promises repaired log report, Up: Standard reports in CFEngine 3 Nova

1.13 Promises repaired summary report

If the Promises repaired log is too detailed for your needs, the Promises repaired summary report eliminates the time stamp of the promises repaired and presents a cumulative summary of promises repaired, i.e. the total number times a promise has been repaired. Click on Promises repaired summary in the ‘Reports finder’ to open a query window:


Promises repaired summary query
Figure: Promises repaired summary query

The Promise repaired summary query can filter by (patterns in) promise handles, host class (i.e. the class/context of a host), and a desired time interval. Leaving the fields blank will result in a report listing all promises that were repaired and their cumulative number of occurrences.

Once you have clicked Generate report, CFEngine 3 Nova will list an overview of promises that suit the query criteria entered above. The results are presented as ‘Promise handle’ (identifier of the promise), ‘Report’ (what was repaired), and ‘Occurrences’ (number of occurrences of repair).


Promises repaired summary report
Figure: Promises repaired summary report


Next: , Previous: Promises repaired summary report, Up: Standard reports in CFEngine 3 Nova

1.14 Promises not kept log report

The Status room in the Nova Mission Portal gives an overview of the general status of your system, including six hour summaries of promises kept, repaired, and not kept from the last week. The Promises not kept log is useful to get a complete overview of the history of promises not kept, including execution order and events that are more than a week old. Click on Promises not kept log in the ‘Reports finder’ to open a query window:


Promises not kept log query
Figure: Promises not kept log query

The Promises not kept log query can filter by (patterns in) promise handles, host class (i.e. the class/context of a host), and a desired time interval. Leaving the fields blank will result in a report listing all promises that were not kept and the time of occurrence.

Once you have clicked Generate report, CFEngine 3 Nova will list an overview of promises that suit the query criteria entered above. The results are presented as ‘Host’ (host name), ‘Promise handle’ (identifier of the promise), ‘Report’ (what was not kept), and ‘Time’ (time stamp of the event). You can add your personal note in the right column, documenting any thoughts or issues that you might have about the query result.


Promises not kept log report
Figure: Promises not kept log report


Next: , Previous: Promises not kept log report, Up: Standard reports in CFEngine 3 Nova

1.15 Promises not kept summary report

If the Promises not kept log is too detailed for your needs, the Promises not kept summary report eliminates the time stamp of the promises repaired and presents a cumulative summary of promises repaired, i.e. the total number times a promise was not kept. Click on Promises not kept summary in the ‘Reports finder’ to open a query window:


Promises not kept summary query
Figure: Promises not kept summary query

The Promise not kept summary query can filter by (patterns in) promise handles, host class (i.e. the class/context of a host), and a desired time interval. Leaving the fields blank will result in a report listing all promises that were not kept and their cumulative number of occurrences.

Once you have clicked Generate report, CFEngine 3 Nova will list an overview of promises that suit the query criteria entered above. The results are presented as ‘Promise handle’, ‘Report’ (what was not kept), and ‘Occurrences’ (the number of times the promise was not kept).


Promises not kept summary report
Figure: Promises not kept summary report


Next: , Previous: Promises not kept summary report, Up: Standard reports in CFEngine 3 Nova

1.16 Setuid/gid root programs report

setuid and setgid (short for "set user ID upon execution" and "set group ID upon execution", respectively) are Unix access right flags that allow users to run an executable with the permissions of the executable's owner or group. They are often used to allow users on a computer system to run programs with temporarily elevated privileges in order to perform a specific task. The ‘Setuid/gid root programs report’ is useful to get an overview of what processes have been elevated to root privileges and potentially uncover security issues.

Click on Setuid/gid root programs in the ‘Reports finder’ to open a query window:


Setuid/gid root programs query
Figure: Setuid/gid root programs query

The Setuid/gid root programs query can filter by (patterns in) file name or host class. Leaving the fields blank will result in a report listing all hosts and files that have their permissions elevated to root.

Setuid/gid root programs report
Figure: Setuid/gid root programs report

Once you have clicked Generate report, CFEngine 3 Nova will list an overview of promises that suit the query criteria entered above. The results are presented as host name and files that have their permissions elevated to root.


Next: , Previous: Setuid/gid root programs report, Up: Standard reports in CFEngine 3 Nova

1.17 Software installed report

The ‘Software installed report’ will list the software packages claimed to be installed according to the local package manager. Click on Software installed in the ‘Reports finder’ to open a query window:


Software installed query
Figure: Software installed query

The Software installed query can filter by (patterns in) software name, version, architecture, or host class. Leaving the fields blank will result in a report listing all hosts and software installed on the system.

Once you have clicked Generate report, CFEngine 3 Nova will list an overview that suits the query criteria entered above. The results are presented as ‘Host’ (host name), ‘Name’ (of software package), ‘Version’ (of software package), and ‘Architecture’ (of machine on which software runs).


Software installed report
Figure: Software installed report


Previous: Software installed report, Up: Standard reports in CFEngine 3 Nova

1.18 Variables report

The ‘Variables report’ is useful for tracking your variables and checking their values, for instance to see if they behave in the expected manner. Click on Variables in the ‘Reports finder’ to open a query window:


Variables query
Figure: Variables query

The Variables query can filter by (patterns in) scope (bundle where the variable is used), Lvalue (name of variable), Rvalue (content of variable), type, or host class. Leaving the fields blank will result in a report listing all variables that were last observed on the system.

Once you have clicked Generate report, CFEngine 3 Nova will list an overview of variables that suit the query criteria entered above. The results are presented in table form/blocks of scope (i.e. in which bundle the variables appear) with the following column format: ‘Host’ (name of host where the variable is defined), ‘Type’ (type of the variable, ‘Name’, and ‘Value’.


Variables report
Figure: Variables report


Previous: Standard reports in CFEngine 3 Nova, Up: Top

2 CDP reports

Content-Driven Policies (CDP) were introduced to make policy management easier. In contrast to policies written in the CFEngine language, they are composed of semi-colon separated fields in a text file that the user fills with content, like a spreadsheet or tabular file. Each line in the file is parsed and results in a specific type of promise being made. Reports based on data from CDP policies can be found in ‘Engineering room’: click the Engineering icon in the Mission Portal, then the CDP reports finder in the Engineering room:


Go to Engineering
Figure: Go to Engineering

Go to CDP reports finder
Figure: Go to CDP reports finder

Reports finder
Figure: CDP reports finder

We will now go through the different CDP reports and their corresponding input files.


Next: , Previous: CDP reports, Up: CDP reports

2.1 ACLs report - File access controls

An access control list (ACL) is a list of permissions attached to an object. An ACL specifies which users or system processes are granted access to objects, as well as what operations are allowed on given objects. Each entry in a typical ACL specifies a subject and an operation. For instance, if a file has an ACL that contains (Alice, delete), this would give Alice permission to delete the file.

Click on ACLs in the ‘CDP Reports finder’ to access the ACLs CDP report:


ACLs report
Figure: ACLs report

The report lists an overview of host name (‘Host’), path of the affected object (‘Path’), the permission setting (‘Permission (ACL)’), owner of the affected object (‘Owner’), action to execute on the object (‘Action’), the context in which the promise was made (‘Class expression’), state of compliance (‘State’), and the time the promise was last checked (‘Last checked’).

The default CFEngine 3 Nova ACLs policies allow you to set permissions to directories and files using two different input files (acl_directory_list.txt and acl_file_list.txt, respectively). We will limit ourselves to look at one of these in the following example as they are conceptually identical.

The file acl_file_list.txt can be found under the cdp_inputs catalog in the policy editor, click it to open:


open ACLs input file
Figure: Open the ACLs input file

The content of the file looks like this (lines have been split and indented for presentability):

   #
   #  ACLs On Files
   #
   #  FORMAT:   path;entity_type1:entity_name1:perms1,
         entity_type2:entity_name2:perms2,...;owner;action;class_expression
   #
   #  EXAMPLE:  C:\tmp;user:Administrator:rwx,user:SYSTEM:r;
         Administrator;fix;windows
   #

   # Windows 2003
   c:\WINDOWS\system32\drivers\etc\hosts;user:Administrator:rw,user:SYSTEM:rw,
       user:Guest:r;SYSTEM;fix;Windows_Server_2003.!Hr09
   c:\WINDOWS\system32\drivers\etc\hosts;user:Administrator:rw,user:SYSTEM:rw,
       user:Guest:rw;SYSTEM;fix;Windows_Server_2003.Hr09
   # Windows 2008
   c:\Windows\System32\drivers\etc\hosts;user:Administrator:rw,user:SYSTEM:rw,
       user:Guest:r;SYSTEM;fix;Windows_Server_2008_R2.!Hr11
   c:\Windows\System32\drivers\etc\hosts;user:Administrator:rw,user:SYSTEM:rw,
       user:Guest:rw;SYSTEM;fix;Windows_Server_2008_R2.Hr11

We need to look at the header of the file to understand its structure. We saw in the CDP reports introduction that the input consisted of lines containing semi colon separated fields, so anything with a ‘;’ before or after it is a field entry. The structure of these fields are explained in the FORMAT section of the file header, here we have:

  #  FORMAT:   path;entity_type1:entity_name1:perms1,
         entity_type2:entity_name2:perms2,...;owner;action;class_expression

Splitting this up into separate fields:

path
Path of file to set permissions on.
entity_type1:entity_name1:perms1
This field defines the permissions (‘perms1’) that a user (‘entity_type1’), and member of the group (‘entity_name1’), has on the file defined in ‘path’.
entity_type2:entity_name2:perms2,...
Same as entity_type1:entity_name1:perms1, but for different user, group, and permission settings.
owner
Defines the owner of the file defined in ‘path
action
Tells CFEngine what to do if the file permissions differ from what was defined in the ACLs policy. Can take the values ‘fix’ (set permissions as defined in ACLs policy), ‘warn’ (log and display a warning that the file permissions differ from what was defined in ACLs policy), and ‘nop’ (no operation; no log entry, but print a warning in command-line interface).
class_expression
Context in which the permissions are set, i.e. a class expression (boolean) that needs to be fulfilled for the permissions to be set.


Next: , Previous: ACLs report - File access controls, Up: CDP reports

2.2 Commands report - Scheduled commands to execute

You may use the Commands CDP to schedule script execution on specific hosts. The Commands CDP uses a combination of class expressions to set the context (i.e. time and place) of execution.

Click on Commands in the ‘CDP Reports finder’ to access the Commands CDP report:


Commands report
Figure: Commands report

The report lists an overview of host name (‘Host’), the command to execute (‘Command’), the class to define if execution fails (‘Failclass’), action to execute if there is an error (‘Action’; see explanation of the CDP input file below for possible values), the context in which the promise was made (‘Class expression’), state of compliance (‘State’), and the time the promise was last checked (‘Last checked’).

The Commands CDP input file, command_list.txt, can be found in the left menu in the cdp_inputs catalog. The content looks like this (lines have been split and indented for presentability):

   #
   #  Command Execution
   #
   #  FORMAT:   command_path;on_error_define_class;action;class_expression
   #
   #  EXAMPLE:  c:\windows\system32\cmd.exe /c "echo hello";hello_failed;fix;
         DomainController
   #
   #  NOTE:     You may use this Content-Driven Policy to schedule script
   #            execution on a class of hosts by using a combination of
   #            host and time classes in class_expression, e.g. set
   #            class_expression to "windows.Tuesday.Hr10.Min30_35".
   #

   c:\windows\system32\cmd.exe /c "eho hello";hello_failed;fix;windows.Hr11
   c:\windows\system32\cmd.exe /c "echo hello";hello_failed;fix;windows.!Hr11
   c:\windows\system32\cmd.exe /c "echo hello failed > c:\reportfile.txt";
       report_failed;fix;hello_failed.windows
   c:\windows\system32\cmd.exe /c "echo hello succeeded > c:\reportfile.txt";
       report_failed;fix;!hello_failed.windows
   /usr/bin/sleep 5;sleep_failed_solaris;fix;solaris
   /bin/sleep 5;sleep_failed_solaris;fix;linux

Again, we need to look at the header of the file to understand its structure:

   #  FORMAT:   command_path;on_error_define_class;action;class_expression

Separating the fields:

command_path
Path of command to execute.
on_error_define_class
Class to define if there is an error in command execution.
action
Tells CFEngine what to do if there is an error in command execution. Can take the values ‘fix’ (attempt to re-execute the command), ‘warn’ (log and display a warning that the command could not be executed), and ‘nop’ (no operation; no log entry, but print a warning in command-line interface).
class_expression
Context in which the command is to be executed, i.e. a class expression (boolean) that needs to be fulfilled for the command to take place. In the above example (windows.Tuesday.Hr10.Min30_35) the command will only be executed on Windows machines on Tuesdays between 10.30am and 10.35am.


Next: , Previous: Commands report - Scheduled commands to execute, Up: CDP reports

2.3 File changes report - File changes observed on the system

We saw that awareness of changes often is considered a major part of infrastructure management in the walk-through of the CFEngine 3 Nova standard reports. The file changes CDP policy differs slightly from the Files changes log report in that it will restore the original file upon detecting a change and report whether the file remains compliant or not.

Click on File changes in the ‘CDP Reports finder’ to access the File changes CDP report:


File changes report
Figure: File changes report

The report lists an overview of host name (‘Host’), the path of the concerned file (‘Path’), the context in which the promise was made (‘Class expression’), time stamp of when a change was detected (‘Last Change Detected’), state of compliance (‘State’), and the time the promise was last checked (‘Last checked’).

The File changes CDP input file, file_change_list.txt, can be found in the left menu in the cdp_inputs catalog. The content looks like this:

   #
   #  File Changes Detection and Revert
   #
   #  FORMAT:   file_path;class_expression
   #
   #  EXAMPLE:  C:\pwd.txt;windows
   #
   #  NOTE:     The file is always restored on change, and change
   #            reports will be generated.
   #            Use file_diff Content-Driven Policy to allow changes.
   #

   /etc/shadow;linux|solarisx86

Looking at the header of the file:

   #  FORMAT:   file_path;class_expression

Separating the fields:

file_path
Path of file to monitor and repair changes on.
class_expression
Context in which the change detection/repair is to be executed, i.e. a class expression (boolean) that needs to be fulfilled for the event to take place.


Next: , Previous: File changes report - File changes observed on the system, Up: CDP reports

2.4 File diffs report - Delta/difference comparison showing file changes

The file diff CDP policy does the same as the File change CDP policy, except that it does not repair the file to original state if a change is detected. Click on File diffs in the ‘CDP Reports finder’ to access the File diffs report:


File diffs report
Figure: File diffs report

The report lists an overview of host name (‘Host’), the path of the concerned file (‘Path’), the context in which the promise was made (‘Class expression’), time stamp of when a change was detected (‘Last Change Detected’), state of compliance (‘State’), and the time the promise was last checked (‘Last checked’).

The File diff CDP input file, file_diff_list.txt, can be found in the left menu in the cdp_inputs catalog. The content looks like this:

   #
   #  File Difference Reporting
   #
   #  FORMAT:   file_path;class_expression
   #
   #  EXAMPLE:  C:\users.txt;windows
   #
   #  NOTE:     The file is always allowed to change. 
   #            Use file_change Content-Driven Policies to revert a 
   #	        changed file. Detailed change reports will 
   #            be generated.
   #

   /etc/group;linux|solarisx86

Looking at the header of the file:

   #  FORMAT:   file_path;class_expression

Separating the fields:

file_path
Path of file to monitor and warn about changes on.
class_expression
Context in which the change detection/warning is to be executed, i.e. a class expression (boolean) that needs to be fulfilled for the event to take place.


Next: , Previous: File diffs report - Delta/difference comparison showing file changes, Up: CDP reports

2.5 Registry report - Promised Windows registry setting status

The Windows Registry is a hierarchical database that stores configuration settings and options on Microsoft Windows operating systems. It contains settings for low-level operating system components as well as the applications running on the platform. Registry keys are similar to folders: in addition to values, each key can contain subkeys, which may contain further subkeys, and so on. Keys are referenced with a syntax similar to Windows' path names, using backslashes to indicate levels of hierarchy. Each subkey has a mandatory name, which is a non-empty string that cannot contain any backslash, and whose letter case is insignificant.

Click on Registry in the ‘CDP Reports finder’ to access the Registry report:


Registry report
Figure: Registry report

The report lists an overview of host name (‘Host’), the key identifier (‘Key’), the key value (‘Value’), action to take if there is an error in the key (‘Action’; see explanation of the CDP input file below for possible values), the context in which the promise was made (‘Class expression’), the state of compliance (‘State’), and the time the promise was last checked (‘Last checked’).

The Registry CDP input file, registry_list.txt, can be found in the left menu in the cdp_inputs catalog. The content looks like this (lines have been split and indented for presentability):

   #
   #  Windows Registry Management
   #
   #  FORMAT:   key;name,type,data;action;class_expression
   #
   #  EXAMPLE:  HKEY_CURRENT_USER\Control Panel\Desktop;ScreenSaverIsSecure,
         REG_SZ,1;fix;windows
   #
   #  NOTE:     Currently, type must be REG_SZ (string).
   #

   HKEY_CURRENT_USER\Control Panel\Desktop;ScreenSaverIsSecure,REG_SZ,1;
      fix;windows.!Hr11
   HKEY_CURRENT_USER\Control Panel\Desktop;ScreenSaverIsSecure,REG_SZ,0;
      fix;windows.Hr11
   HKEY_CURRENT_USER\Control Panel\Desktop;ScreenSaveTimeOut,REG_SZ,600;
      fix;windows.!Hr11
   HKEY_CURRENT_USER\Control Panel\Desktop;ScreenSaveTimeOut,REG_SZ,1200;
      fix;windows.Hr11

Looking at the header of the file:

   #  FORMAT:   key;name,type,data;action;class_expression

Separating the fields:

key
The path to the key in question.
name,type,data
Name, type, and value of the key.
action
Tells CFEngine what to do if there is a difference between the registry entry and the definition in the Registry CDP. Can take the values ‘fix’ (set the registry entry as defined in the Registry CDP), ‘warn’ (log and display a warning that the there is a discrepancy between the registry entry and the Registry CDP), and ‘nop’ (no operation; no log entry, but print a warning in command-line interface).
class_expression
Context in which the promise is to be executed, i.e. a class expression (boolean) that needs to be fulfilled for the command to take place.


Previous: Registry report - Promised Windows registry setting status, Up: CDP reports

2.6 Services report - System service status

Services are programs that once started run continuously in the background. They perform specific functions which are designed not to require user intervention and are ready for input or monitor changes in your system and respond to them. For example, the Apache server has a daemon called httpd that listens on port 80 on your machine. When it receives a request for a page it sends the appropriate data back to the client machine.

With the three lines of semicolon separated fields, we ensure the correct status of three services on all our Windows machines and are given specialized reports on the outcome. The Content-Driven Policy services report is shown below. Click on Services in the ‘CDP Reports finder’ to access the Services report:


Services report
Figure: Services report

The report lists an overview of host name (‘Host’), ‘Service Name’, the runstatus of the service (‘Runstatus’), action to take if there is a difference from policy (‘Action’; see explanation of the CDP input file below for possible values), the context in which the promise was made (‘Class expression’), the state of compliance (‘State’), and the time the promise was last checked (‘Last checked’).

The Registry CDP input file, service_list.txt, can be found in the left menu in the cdp_inputs catalog. The content looks like this (lines have been split and indented for presentability):

   #
   #  Windows Service Management
   #
   #  FORMAT:   service_name;run_status;action;class_expression
   #
   #  EXAMPLE:  Dnscache;start;fix;windows
   #
   #  NOTE:     Service name is not the "Display name" 
   #            -- see the properties of the service. 
   #            run_status can be start/stop/disable. If start then 
   #            the service is started, if disable then service is 
   #            stopped and "Startup type" is set to disable,
   #   	        if stop, then service is stopped "Startup type" is left 
   #            unchanged.
   #

   Dnscache;stop;fix;windows.Hr10
   wuauserv;stop;fix;windows.Hr10
   Dnscache;start;fix;windows.!Hr10
   wuauserv;start;fix;windows.!Hr10

Looking at the header of the file:

   #  FORMAT:   service_name;run_status;action;class_expression

Separating the fields:

service_name
Name of the service (not necessarily the same as the display name, see properties of the service).
run_status
The run status of the service defines whether it should be running or not. Can take the values ‘start’, ‘stop’, or ‘disable’ (will stop the service and change its startup mode to disable, i.e. will not be restarted upon reboot of the machine, for example).
action
Tells CFEngine what to do if there is a difference between the run status what has been defined in the Services CDP. Can take the values ‘fix’ (set the run status as defined in the Services CDP), ‘warn’ (log and display a warning that the there is a discrepancy between the run status and the Services CDP), and ‘nop’ (no operation; no log entry, but print a warning in command-line interface).
class_expression
Context in which the promise is to be executed, i.e. a class expression (boolean) that needs to be fulfilled for the command to take place.


Footnotes

[1] See also section on Vital signs in the CFEngine 3 Nova Owner's Manual.