Configuration concepts

We adopted the following terms to describe the configurations in Rudder:

Technique: This is a configuration skeleton, adapted to a function or a particular service (e.g. DNS resolver configuration). This skeleton includes the configuration logic for this function or service, and can be set according to a list of variables (in the same example: IP addresses of DNS servers, the default search box, …)
Directive: This is an instance of a Technique, which allows to set values for the parameters of the latter. Each Directive can have a unique name. A Directive should be completed with a short and a long description, and a collection of parameters for the variables defined by the Technique.
Rule: It is the application of one or more directives to a group of nodes. It is the glue between both Asset Management and Configuration Management parts of the application.
Applied Policy: This is the result of the conversion of a Policy Instance into a set of CFEngine Promises for a particular Node.

As illustrated in this summary diagram, the rules are linking the functions of inventory management and configuration management.

Figure 1. Concepts diagram

Techniques

Concepts

A technique defines a set of operations and configurations to reach the desired behaviour. This includes the initial set-up, but also a regular check on the parameters, and automatic repairs (when possible).

All the techniques are built with the possibility to change only part of a service configuration: each parameter may be either active, either set on the "Don’t change" value, that will let the default values or in place. This allows for a progressive deployment of the configuration management.

Finally, the techniques will generate a set of reports which are sent to the Rudder Root Server, which will let you analyse the percentage of compliance of your policies, and soon, detailed reports on their application.

Manage techniques

Techniques shipped with Rudder are presented in a library that you can reorganize in Configuration → Techniques. The library is organized in two parts: the available techniques, and the selection made by the user.

Technique Library: This is an organized list of all available Techniques. This list can’t be modified: every change made by a user will be applied to the Active Techniques.
Active Techniques: This is an organized list of the Techniques selected and modified by the user. By default this list is the same as the Technique Library. Techniques can be disabled or deleted, and then activated again with a simple drag and drop. Categories can be reorganised according to the desired taxonomy. A Technique can appear only once in the Active Techniques list.

Create new techniques

The standard library only provides the most common techniques. You can create new technique with the Technique Editor.

Directives

Once you have selected and organized your techniques, you can create your configurations in the Configuration Management → Directives section.

Directive: This is an instance of a Technique, which allows to set values for the parameters of the latter. Each Directive can have a unique name. A Directive should be completed with a short and a long description, and a collection of parameters for the variables defined by the Technique.

The screen is divided in three parts:

on the left, The list of directives, grouped by technique
on the right, The selected directive form.

Click on the name of a technique to show its description, and how to create a directive base on it.

Click on the name of a directive to see the directive summary containing the description of the technique its derived from, and the configuration items of the directive.

Example 1. Create a directive for Name resolution

Use the technique 'Name resolution' to create a new directive called Google DNS Servers, and shortly described as 'Use Google DNS Server'. Check in the options 'Set nameservers' and 'Set DNS search suffix'. Set the value of the variable 'DNS resolver' to 8.8.8.8 and of 'Domain search suffix' according to your organization, like example.com.

Rules

Rule: It is the application of one or more directives to a group of nodes. It is the glue between both Asset Management and Configuration Management parts of the application.

When a rule is created or modified, the policies for the target nodes are generated. Rudder computes all the policies each nodes must have, and makes them available for the nodes. This process can take up to several minutes, depending on the number of managed nodes and the Policy Server configuration. During this time, The status icon on the top of the page turns to grey, with moving arrows. if you feel the generated policies should be modified (for instance, if you changed the configuration of Rudder), you can click on the status menu in the top bar and click on "Regenerate policies"

Variables and Values

Values used in directives, parameters and properties have several types - parameters and properties are either String or JSON, while in directives they can be free String, String validated by regular expression, or Javascript.

These values are automatically escaped to be managed correctly. The escaping doubles the backslashes ( \ → \\ ), and replace a quote by a backslash quote ( " → \\") on Linux/Unix systems, and on Windows it replaces a quote by a backtick quote ( " → `" ), and doubles the backticks.

Values in the Technique Editor in Rudder 6.X are not escaped - their content needs to be escaped, based on the previous rules. Starting in Rudder 7.0, values in Technique Editor are escaped properly.

Prior to upgrading from 6.X to 7.0, you need to review values in Techniques from the Technique Editor to detect any unescaped ", \ and ` Safest approach is to disable these Techniques for the upgrade, and unescape the values and enable back the Techniques once upgrade to 7.0 is done

Rudder provides multiple ways to add common and reusable variables in either plain directives, or techniques created using the technique editor. See Variables for more details.

Compliance and Drift Assessment

Overview in Rudder

Rudder is built to continuously assess drift compared to defined policies, with or without auto-healing.

By auto-healing, we mean that optionally, Rudder can continuously enforce correct configuration over time, correcting the assessed drift so that your configuration converges towards desired states. This behavior is optional, and Rudder can only report drift without changing configuration. That policy enforce or audit mode can be configured by node, rule or directive (see policy mode documentation for more details).

Rudder is able to adapt to complex process and only do the minimal required work so that the server converges to the desired state, and so whatever was the starting state point. Rudder works as a GPS would, adapting the path to your destination depending of the path you actually took. This process is much more resilient to changes than a step by step, procedural description of the commands to execute.

Compliance and drift from expected configurations are then reported with possibility to drill down in non-compliance issues to identify the root problem.

Of course, one can always correct a drift error by hand by updating configuration target and changing policy mode from "audit" to "enforce" mode.

Compliance and drift reporting

Compliance drifts (non-compliance, enforcement errors, repairs) are reported in Rudder by several means:

Compliance are reported in aggregated format globally in the dashboard, and by rules or nodes (example for rule below)
they are stored in Rudder compliance database, and each rule displays an history of changes as depicted in "Changes history on a rule" below.
each drifts fires an event which is logged in file /var/log/rudder/compliance/non-compliant-reports.log and can be used to integrates with log aggregation engine like Logstash, or hooks (typically to send notification to IRC or Slack, send email, etc)
see for example the Slack connector here: https://github.com/Normation/rudder-tools/blob/master/scripts/rudder-notification/forward-non-compliance-to-slack.sh
compliance and drift are also available from Rudder API to provide deeper integration with your IT Infrastructure.

Figure 2. Compliance on a rule

The rule detailed compliance screen will also graph compliance deviations on a recent period as well as display a deviation log history for this period.

Figure 3. Changes history on a rule

How compliance is calculated?

As previously seen, in Rudder you define rules which target groups of nodes, and are composed of configuration directives.

A directive contains one or multiple sub-configuration elements which generates reports. For example, for a Sudoers directive, each user can be such an element.

Reports have states explaining what is the drift between the expected configuration and the actual configuration. Some states depends if the user choose to automatically enforce drift correction or if he chose to only reports on drift).

Finally, a node can get a global state if reports don’t come at expected frequency or for expected policy configuration version.

Below you will find all details about the possible states and their meaning with the actual compliance calculus method.

Checking that the node is correctly reporting, at correct frequency

At the node level, we are checking that the node is sending reports according to the expected frequency, and for the currently defined version of the configuration for it.

Based on this information, we get a

Applying: When a new set of policies are defined for a node (or any update to existing one), Rudder waits during a grace period for reports so that the node has time to apply the new policies. During this period, the configuration is said 'Applying'.
No report: The system didn’t send any reports since a time incompatible with the agent frequency run interval. Most likelly, the node is not online or there is an ongoing network issue between the node and Rudder server.

At directive level: checking for drift and auto-healing

Success or Compliant: The system is already in the desired state. No change is needed. Conformity is reached.
Repaired: When a configuration policy is "enforced", that state means that the system was not in the desired state. Rudder applied some change and repaired what was not correct. Now the system is in the desired state.
Error: When configuration is enforced, it means that the system is not in the desired state and Rudder wasn’t able to repair the system.
Non compliant: When configuration is not enforced, it means that the systemn is not in the desired state. A drift is reported.
Not applicable: A specific configuration may not be applicable on a given node because some precondition are not met. For example, the specified configuration is only relevant for Linux nodes, and thus is Not applicable on a Windows server.
Unexpected: We have a special kind of report for unexpected states (both for enforce and audit mode). These reports generally mean that the node is sending reports for unexpected configuration components. It may be due to bad parameters for the configuration, or an error in the technique.

Compliance calculus

Based on these facts, the compliance of a rule is calculated like this:

Number of nodes for which conformity is reached for every directive of the rule / Total number of nodes on which the rule has been applied

Policy Mode (Audit/Enforce)

Rudder includes a policy mode setting, that allows two distinct behaviors:

Audit: Test if the system is in the desired state, and report about it
Enforce: Test if the system is in the desired state, if not, try to act to get to this state, and report about actions taken and final state

This allows for example to use Rudder as an audit tool or to test a policy before enforcing it.

audit mode general overview

This mode can be set:

Globally on the Rudder root server, in the Settings > General page. In this can case there are two options: allow to override this mode on specific items, or use the global configuration everywhere.
On a directive, in the directive configuration form,
On a node, from the Node details > Settings page,
From the node itself, which will override the mode configured on the Rudder server, thanks to rudder agent set-force-audit and rudder agent unset-force-audit commands.

A lot of attention and several safeguards have been put in place to ensure that if you choose to use "Audit" for a target, nothing will be changed on the node for that target (except Rudder’s own configuration under /var/rudder), and only some harmless commands will be run (like listing installed packages or refreshing package lists).

Nodes are fully aware of exactly what directives need to be executed in Audit or in Enforce mode, and the "rudder agent" command line has been enhanced to let you see the result with a glimpse: the first column in rudder agent run output is now the mode (A for Audit and E for Enforce), and the compliance summary is split by audit mode. In addition to pre-existing technical reports, new ones have been added to report on "audit-compliant" (the check was OK), "audit-non-compliant" (the check was done, but the result is not the one expected), "audit-not-applicable" (the check is not applicable for that node, for example because of a limitation on the OS type), "audit-error" (the check wasn’t able to finish correctly) status.

How is the effective mode computed?

We will here explain what is the computation made during generation to decide which mode to apply to a directive on a node, based on the current settings.

The short rule is: Override wins, then Audit wins

For a given directive on a given node at a given time, we have three different policy mode settings:

The global mode, called G, which can be Audit or Enforce
The node mode called N, which can be Global (if not overridden), Audit, or Enforce
The directive mode, called D, which can be Global (if not overridden), Audit, or Enforce

The result is:

If override is not allowed, the policy mode is always the global mode G.
If override is allowed:
- If N and D are set to use the Global default value (i.e. no override), the policy mode is the global mode G.
- If N uses the global value and D is overridden to Audit or Enforce, the D value is used.
- If D uses the global value and N is overridden to Audit or Enforce, the N value is used.
- If N and D are overridden to Audit or Enforce, the value is Audit if at least one of N or D is Audit, Enforce if both are in Enforce mode

Reporting Mode (non-compliant only)

The main goal of Rudder is to compute compliance of configured rules on nodes by comparing the list of check results sent back by a node in its compliance reports with the list of expected checks for that node that Rudder knows about, and of course that the value of each check matches what is expected.

This modelization of what Rudder expects allow it to be sure that all checks were actually done correctly. This reporting mode is the default one in Rudder, and is called full compliance reporting mode.

On some cases, especially when bandwidth between nodes and Rudder is low or when there is a really big number of nodes with lots of checks, you may want to reduce the number of check statuses sent in reports. For that, there is a setting allowing to send only non-compliant checks in report. Since Rudder keeps a model of what is expected to be checked, Rudder can then compute what check were actually done by assuming that the missing one are successes.

On extreme cases, for example for embedded hardware with costly network data plan, you may want to totally disable reporting. In that case, Rudder will assume that the node is doing what it needs and Rudder will not put a "no answer" status for it, even if it does not get reports back.

The setting is available either globally in the Settings menu (see image below), or on a node-by-node basis in its setting tab.

We strongly advise to keep the default configuration and use the Full compliance mode.

Global configuration of reporting mode

← Advanced node management Technique editor →