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.

configuration concepts
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 the Techniques

The 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.

Directive management
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.

Rule management

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"

Rule config

Variables

User defined parameters

Rudder provides a simple way to add common and reusable variables in either plain Directives, or techniques created using the Technique editor: the parameters.

Parameters

The parameters enable the user to specify a content that can be put anywhere, using the following syntax:

  • In Directives: ${rudder.param.name} will expand the content of the "name" parameter.

  • In the Technique Editor: ${rudder_parameters.name} will do the same.

Using this, you can specify common file headers (this is the default parameter, "rudder_file_edit_header"), common DNS or domain names, backup servers, site-specific elements…​

System variables

Rudder also provides system variables that contain information about nodes and their policy server. You can use them like user defined parameters.

These variables are only usable in the directive parameters and not in the technique editor, see node-level properties below if needed.

The information about a Node:

  • ${rudder.node.id} returns the Rudder generated id of the Node

  • ${rudder.node.hostname} returns the hostname of the Node

  • ${rudder.node.admin} returns the administrator login of the Node

The information about a Node’s policy server.

  • ${rudder.node.policyserver.id} returns the Rudder generated id of the Policy Server

  • ${rudder.node.policyserver.hostname} returns the hostname of the Policy Server

  • ${rudder.node.policyserver.admin} returns the administrator login of the Policy Server

Node-level system properties

These variables are not available on Windows nodes, but only on with the classic Linux/AIX agent.

These properties are evaluated on the node at run time, and are hence available both in directives parameters and in the technique editor:

  • ${sys.fqhost} is the fully-qualified hostname, it matches the hostname seen in Rudder

  • ${sys.uqhost} is the unqualified hostname

  • ${sys.host} is the node’s hostname (according to the kernel)

  • ${sys.domain} is the domain discovered by the agent

There are also more variables available, all documented in this page.

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.

Rule compliance
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.

Changes compliance history
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

audit mode general overview

This mode can be set:

  • Globally on the Rudder root server. 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.

  • On a node.

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