Rudder techniques

This guide covers the usage of YAML-based techniques in Rudder, including the techniques syntax and usage of the rudderc tool.

Overview

Techniques in Rudder are system configuration or audit templates, which can include extra files and take parameters. They are instantiated by directives, which are in turn linked to rules to be applied. Techniques are based on building blocks called methods, which control basic items (like the content of a file or its permissions).

Rudder includes a graphical editor for techniques, providing easy access creation and customization of configuration policies in Rudder.

In addition to this visual editor, it is possible to create and modify techniques as code, in YAML format, like:

---
id: "ntp"
name: "NTP configuration"
version: "0.1"
description: "This technique configures the local ntp service"
documentation: "**Markdown** formatted documentation."
items:
  - name: "NTP configuration"
    id: d86ce2e5-d5b6-45cc-87e8-c11cca71d907
    method: file_content
    condition: "debian"
    params:
      path: "/etc/ntp.conf"
      lines: "server ntp.org"
      enforce: "true"

These two representations are equivalent, and you will soon be able to use both of them to edit the same technique.

Installation

• rudderc is built into the Rudder server. The binary is available in /opt/rudder/bin/rudderc.
• On other systems, like workstations, you can download a pre-built binary for Linux or Windows x86_64 in the repository.

To be able to check and compile techniques, the rudderc program needs access to the method library of the target systems. When running on a Rudder server, which has a built-in rudderc binary, the local library will be used. The standalone binary from the repository includes the default library. You can override the default library by passing a --library argument.

Usage

The rudderc CLI

Rudder comes with a tool dedicated to the techniques development and usage. It is especially important as techniques are not run as YAML, but compiled into an executable policy file depending on the target platform. There are currently two possible targets, which are the platforms Rudder has agents for:

• Linux/AIX
• Windows

These platforms use different agent technology, but the YAML policies unify them.

Create a technique

To setup the technique structure:

$ rudderc new my_technique
       Wrote ./my_technique/technique.yml

$ cd my_technique

This will create the base structure of your new technique:

my_technique/
  ├── technique.yml
  ├── resources/
  └── tests/

The technique.yml is the technique content, and the resources directory can be used to include external files (configuration files, templates, etc.). The tests directory will contain your technique's tests. All files produced by rudderc will be placed in the target directory.

Check a technique

You can check the current technique syntax with:

$ rudderc check
        Read 179 methods (/path/to/methods/lib)
   Compiling my_technique v0.1 [Linux]
   Compiling my_technique v0.1 [Windows]
     Checked technique.yml

This will check the technique schema and check the compilation to the target platforms.

Compile for the target platforms

$ rudderc build
        Read 179 methods (/path/to/methods/lib)
   Compiling my_technique v0.1 [Linux]
       Wrote target/technique.cf
   Compiling my_technique v0.1 [Windows]
       Wrote target/technique.ps1
  Generating my_technique v0.1 [Metadata]
       Wrote target/metadata.xml
      Copied resources

Clean files

The clean command allows removing all generated files.

$ rudderc clean
     Cleaned target

Build the documentation

You can build this documentation directly using rudderc. This can be specially useful if you use custom methods not present in the public documentation.

$ rudderc lib
        Read 179 methods (/.../ncf/tree/30_generic_methods/)
Book building has started
Running the html backend
       Wrote target/doc/book/index.html

To open the documentation in your browser after build, pass the --open option.

Import a technique into Rudder

As a technique editor technique (using the HTTP API)

You can export your current technique with:

$ rudderc build --export
     Writing ./target/ntp_technique-0.1.zip

The file is named after the technique id and versions. This will produce a configuration archive importable on a Rudder server using the archives HTTP API:

curl --header "X-API-Token: yourToken" -X POST https://rudder.example.com/rudder/api/latest/archives/import --form "archive=@ntp_technique-0.1.zip"

The technique will then be available for normal use.

As a technique editor technique (on the server file system)

The technique editor is able to directly use the YAML format (but does not support technique parameter types for now, and does not display tags). You can either import the technique using the import button in the Web interface, or if you want to automate it, with:

cd /var/rudder/configuration-repository/
mkdir -p CATEGORY/MY_TECHNIQUE/1.0/
cp /path/to/technique.yml  CATEGORY/MY_TECHNIQUE/1.0/
git add CATEGORY/MY_TECHNIQUE/
git commit -m "Add my technique"
rudder server reload-techniques

As a built-in technique

To add a YAML technique as a built-in technique, which gives access to the full power of parameter types, you need to run these commands on your server:

rudderc build
cd /var/rudder/configuration-repository/techniques/
mkdir -p CATEGORY/MY_TECHNIQUE/1.0/
cp -r /path/to/technique/target/* CATEGORY/MY_TECHNIQUE/1.0/
git add CATEGORY/MY_TECHNIQUE/
git commit -m "Add my technique"
rudder server reload-techniques

Warning: rudder server reload-techniques is an asynchronous command. It returns immediately with a success, and you need to check web application logs for errors (/var/log/rudder/webapp/) afterwards.

Once imported, the technique will be available like built-in ones, in the directives' page. To update the technique, repeat the import steps.

Editor/IDE integration

We provide a JSON schema for Rudder YAML techniques. This schema can be automatically used for all your techniques files in most editors, as it's part of JSON Schema Store.

Visual Studio Code

You need to install the YAML plugin in the extension manager:

You're all set! Now, when you open any technique file, the schema will be applied automatically as shown in the file type indicating "Rudder technique".

You now have access to basic linting and autocompletion on technique fields:

Other editors

You can also use:

• All JetBrains editors (IntelliJ IDEA, PyCharm, etc.) work without any configuration
• All editors using the YAML language server (Helix after installing yaml-language-server, SublimeText with the LSP-yaml plugin, etc.)
• NeoVim using the SchemaStore plugin

Technique syntax

General organization

A technique is made of:

• General metadata: its name, version, documentation, etc.
• Parameters it can take
• Resource file that can be attached
• A method tree (made of blocks and leaf methods)

Technique

• id: Unique identifier of the technique. Must only contain alphanumeric or underscore characters.
• name: Human-readable name of the technique
• version: Version in the X.Y format.
• description (optional): Single line description of what the technique does.
• documentation (optional): Documentation in Markdown format.
• tags (optional): Optional key-value tags.
• category (optional): Rudder category to put the technique in.
• params (optional): A list of parameters. See below for details.
• items: A list of items (block or method call). Cannot be empty. See below for details.

Example:

id: "ntp"
name: "NTP configuration"
version: "1.0"
description: "This technique configures the local ntp service"
documentation: "**Warning**: it installs
                the [chrony](https://chrony.tuxfamily.org/) service."

Parameters

The parameters of the technique will be rendered in the directive form. Each parameter contains the following fields:

• id (optional): UUID identifying the parameter.
• name: Name of the parameter. Must only contain alphanumeric or underscore characters.
• description (optional): Single line description of what the parameter does.
• documentation (optional): Documentation (plain text, not in Markdown format).
• type (optional): The type of the parameter, can be:
  • string: A simple string.
  • multiline-string (default): A multiline string (displayed in a textarea).
  • json: A JSON value.
  • yaml: A YAML value.
  • boolean: A boolean value.
  • mail: A valid email address.
  • ip: A valid IP address.
  • ipv4: A valid IPv4 address.
  • ipv6: A valid IPv6 address.
  • integer: An integer.
  • size-b, size-kb, size-mb, size-gb, size-tb: A size in a given unit (B, kB, MB, GB, TB).
  • permissions: Permissions applicable to a file.
  • shared-file: A file in the server's shared-files folder.
  • password: A password value for a Unix system (in /etc/shadow format), which provides specific behavior. See the password_hashes constraint.
• default (optional): The default value of the parameter.
• constraints (optional): Additional restrictions on the value.
  • allow_empty (bool, optional): Whether an empty value is acceptable for this parameter.
  • regex (optional): Restricts allowed value with a regular expression. Defined with:
    • value: The regular expression.
    • error_message (optional): A message to give the user in case the value does not match.
  • select (optional): Allows restricting possible values to a given set. Defined as:
    • An array of:
      • value: The associated value
      • name (optional): The displayed name (value's value by default)
  • password_hashes (optional): A comma-separated list of password hashes types to accept in a password typed field. By default, only accepts pre-hashed values or sha2-crypt algorithms. Available values:
    • pre-hashed: A pre-hashed value in the /etc/shadow format.
    • plain: Plain text password, which will not be modified.
    • unix-crypt-des: DES crypt hash.
    • md5: Simple md5 hash.
    • sha1 Simple sha1 hash.
    • sha256 Simple sha256 hash.
    • sha512 Simple sha512 hash.
    • md5-crypt: md5-crypt hash.
    • sha256-crypt: sha256-crypt hash.
    • sha512-crypt: sha512-crypt hash.
    • md5-crypt-aix: md5-crypt hash for AIX.
    • sha256-crypt-aix: sha256-crypt hash for AIX.
    • sha512-crypt-aix: sha512-crypt hash for AIX.

Example:

params:
  - name: dns_server
    description: "The DNS server hostname"
    default: "1.1.1.1"
    constraints:
      allow_empty: true
  - name: ntp_server
    constraints:
      select:
        - value: "192.123.23.21"
          name: "DC1"
        - value: "192.123.22.21"
          name: "DC2"

Blocks

Blocks contains:

• id (optional): UUID identifying the block.
• name: Human-readable name of the block
• tags (optional): Optional key-value tags.
• items: A list of items (block or method call). Cannot be empty.
• condition (optional): A condition expression for the whole block. true is an always defined (default), false is never defined.
• policy_mode_override (optional):
  • none(default): Use the policy mode from parent container (or directive if no override)
  • enforce: Force the policy mode of all items within the block to enforce mode.
  • audit: Force the policy mode of all items within the block to audit mode.
• reporting (optional):
  • mode
    • weighted (default)
    • worst-case-weighted-sum: Take the worst outcome from all the method calls in the block
    • worst-case-weighted-one: Take the worst outcome from as the block as if it was a single method
    • focus: Apply the outcome of one of the included methods to the whole block, requires passing the id value
    • disabled: No reporting
  • id (required with focus mode): id of the method to focus reporting on.

items:
  - name: "Ensure telnet-server absence"
    tags:
      cve: CVE-2022-3456
    condition: "debian"
    reporting:
      mode: worst-case-weighted-one
    items:
      - ...
      - ...

Methods

Methods contains:

• method: Method technical name (also called "Technique ID").
• id (optional): UUID identifying the method.
• name (optional): Name used in reporting, identifying what the method does. It uses the method name by default.
• tags (optional): Optional key-value tags.
• params: Key-Value dictionary of parameters for the method.
• condition (optional): A condition expression for the method. true is an always defined (default), false is never defined.
• policy_mode_override (optional):
  • none (default): Inherit policy mode from parent container (ore directive if no override)
  • enforce: Force the policy mode to enforce mode.
  • audit: Force the policy mode to audit mode.
• reporting (optional)
  • mode
    • enabled (default): Normal reporting
    • disabled: No reporting

The methods are documented in the next section of this documentation, sorted by category.

Example:

items:
  - name: "Ensure telnet-server absence"
    tags:
      cve: CVE-2022-3456
    condition: "debian"
    method: package_absent
    params:
      name: "telnet-server"
    reporting:
      mode: disabled

Resources

Files can be attached to a technique, they will automatically be deployed in the policies when used on a node. The absolute path of the folder containing the resource files is accessible from within a technique using the variable ${resources_dir}.

To add resources to a YAML technique, put the files under a resources folder in the technique directory. In the example below, the file1.txt will be available from within the technique using ${resources_dir}/file1.txt.

my_technique
├── resources
│   └── file1.txt
├── technique.yml
└── tests

Testing

Write technique tests

NOTE: Not all methods can run successfully with this testing method. In particular all methods exchanging files with the Rudder server won't work.

The tests are placed in a tests folder in the technique directory. Each test case is defined by a YAML file in this folder.

The format of the test case file is:

• target (optional): Target platform, unix or windows. Defaults to unix.
• params (optional): Named parameters passed to the technique in as key-values.
• conditions (optional): Conditions to define before running the technique.
• policy_mode (optional): The mode to use for running the technique. audit or enforce, defaults to enforce.
• setup (optional): Steps to run sequentially to prepare the environment for the test.
• check: Test steps, run sequentially. If one of them fails the test will be considered as a failure.
• cleanup (optional): Steps to run sequentially after the test to clean the environment.

Supported steps:

Steps are usable in setup, check and cleanup stages:

• sh:
  • On Linux: executes commands in a shell (/usr/bin/sh), fails if the return code is not 0
  • On Windows: executes commands in powershell, encapsulated in a script, fails if the exit code is not 0 or if an exception was thrown

Example:

target: windows
params:
  param1: value1
  param2: true
conditions:
  - condition1
  - condition2
policy_mode: audit
setup:
  - sh: "touch /my/file"
check:
  # Linux target
  - sh: "test -f /my/file"
  # Windows target
  - sh: "if (Test-Path -Path C:\\my\\file) { exit 0 } else { exit 1 }"
cleanup:
  - sh: "rm -f /my/file"

The detailed test process is, for each *.yml file in the tests directory:

• Build the technique in standalone mode (i.e. equivalent to passing --standalone to the build command). This adds a prelude to the technique allowing it to run without a Rudder server.
• Run the setup commands sequentially. The commands are called in a shell.
• Run an agent locally, which will:
  • Load all methods from the library
  • Read the parameters values from the YAML test case
  • Define the conditions from the YAML test case
  • Run the technique with the given parameters
• Run the check commands sequentially. The commands are called in a shell.
• Run the cleanup commands sequentially, regardless of the result of the check commands.

The build stops when it encounters a command returning a non-zero return code.

Run technique tests

To run the test case1 from:

my_technique/
  ├── technique.yml
  ├── resources/
  └── tests/
        ├── case1.yml
        └── case1.conf.ref

Run the following:

# Run all defined tests
rudderc test --library /path/to/lib
# Run only the case1 test
rudderc test --library /path/to/lib case1

• When running this command outside a Rudder server, you need to pass it a library path (as it is required to run the agent).
  • It can be the tree directory in a clone of the ncf repository.
  • On Windows it can be the path to an agent installed locally or a decompressed msi.
• the optional argument allows filtering the tests, only run those containing the given string.

Test outputs

The test runner will parse the agent output and place it in JSON format into target/<case_name>.json. It is written before running check steps, so you can use it to assess reporting output (for example, using jq in a shell script).

For convenience, check steps have an environment variable REPORTS_FILE pointing to the current reports JSON.

The JSON file contains an array of entries:

[
  {
    "component": "Ensure correct ntp configuration",
    "key_value": "/tmp/rudderc_test_one",
    "event_type": "result_repaired",
    "msg": "Insert content into /tmp/rudderc_test_one was repaired",
    "report_id": "d86ce2e5-d5b6-45cc-87e8-c11cca71d907",
    "logs": []
  }
]

audit_from_command

Execute an audit only command and reports depending on exit code.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${command} with its actual canonified value.

• ✅ Ok: audit_from_command_${command}_ok
  • ☑️ Already compliant: audit_from_command_${command}_kept
  • 🟨 Repaired: audit_from_command_${command}_repaired
• ❌ Error: audit_from_command_${command}_error

Example

method: audit_from_command
params:
  compliant_codes: VALUE
  command: VALUE

Documentation

Execute an audit only command and reports depending on the exit codes given in parameters. If an exit code is not in the list it will lead to an error status. The command is always executed and the report is adapted to work properly in enforce and in audit mode. It is up to you to make sure the command doesn't modify the system status at all since it is always executed, even in audit mode.

audit_from_osquery

Audit a system property through osquery.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${query} with its actual canonified value.

• ✅ Ok: audit_from_osquery_${query}_ok
  • ☑️ Already compliant: audit_from_osquery_${query}_kept
  • 🟨 Repaired: audit_from_osquery_${query}_repaired
• ❌ Error: audit_from_osquery_${query}_error

Example

method: audit_from_osquery
params:
  comparator: =
  query: VALUE
  value: VALUE

Documentation

This method uses osquery to fetch information about the system, and compares the value with the given one, using the provided comparator.

Parameters

• query is an osquery query returning exactly one result
• comparator is the comparator to use: "=" for equality, "!=" for non-equality, "~" for regex comparison
• value is the expected value, can be a string or a regex depending on the comparator

Setup

This method requires the presence of osquery on the target nodes. It won't install it automatically. Check the correct way of doing so for your OS.

Building queries

To learn about the possible queries, read the osquery schema for your osquery version.

You can test the queries before using them with the osqueryi command, see the example below.

osqueryi "select cpu_logical_cores from system_info;"

You need to provide a query that returns exactly one value. If it's not the case, the method will fail as it does not know what to check.

Examples

# To check the number of cpus on the machine
audit_from_osquery("select cpu_logical_cores from system_info;", "2");

Will report a compliant report if the machine has 3 cores, and a non compliant one if not.

audit_from_powershell_execution

Execute a Powershell command, script or binary (even in audit mode) and parse its output to report a succes or an error.

⚙️ Compatible targets: Windows

Parameters

Outcome conditions

You need to replace ${command} with its actual canonified value.

• ✅ Ok: audit_from_powershell_execution_${command}_ok
  • ☑️ Already compliant: audit_from_powershell_execution_${command}_kept
  • 🟨 Repaired: audit_from_powershell_execution_${command}_repaired
• ❌ Error: audit_from_powershell_execution_${command}_error

Example

method: audit_from_powershell_execution
params:
  command: VALUE
  successRegex: VALUE

Documentation

Execute either a command, a script or a binary even in audit mode - it supports piping.

It will:

• report a success if the execution succeeds and the output matches the given regex.
• report an error otherwise.

Powershell scripts exiting with non-zero return codes will be flagged as failed.

Note: the command will be executed even in Audit mode, it is up to you to make sure it does not impact the system at all.

Note: the regular expression/string to compare to the output are not anchored and are case insensitive.

Examples:

To return success if process explorer is running, the command parameter needs to be

Get-Process | ForEach { ${const.dollar}_.ProcessName }

as the output of the command is a toString() on the generated objects, so you need to extract the relevant data. And the successRegex needs to be explorer.

command_execution

Execute a command.

⚙️ Compatible targets: Linux, Windows

Parameters

Outcome conditions

You need to replace ${command} with its actual canonified value.

• ✅ Ok: command_execution_${command}_ok
  • ☑️ Already compliant: command_execution_${command}_kept
  • 🟨 Repaired: command_execution_${command}_repaired
• ❌ Error: command_execution_${command}_error

Example

method: command_execution
params:
  command: VALUE

Documentation

Execute the Command in shell.

On Unix based agents, the method status will report:

• a Repaired if the return code is "0"
• an Error if the return code is not "0"

On Windows based agents the command is executed through Powershell and its & operator. The method status will report:

• an Error in Audit mode as the command will not be executed
• an Error in Enforce mode if the command did throw an exception
• an Error in Enforce mode if the LASTEXITCODE of the execution was not 0. This can happen when calling '.exe' binaries for instance.
• a Repaired in any other cases

Do not use the "exit" command on Windows as the shell used is the same than the one running the agent!

Windows examples

# A simple command execution
Write-Output "rudder test" | Out-File "C:\test.txt

# Another one with a statement, will report a Repaired if the folder exists,
# and an error if it does not.
{
  if ( (Test-Path "C:\Program Files\Rudder" -PathType Container)) {
    "Rudder folder found!"
  } else {
    throw "Rudder folder does not exist!"
  }
}

command_execution_as_user

Execute a command as a given user.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${command} with its actual canonified value.

• ✅ Ok: command_execution_as_user_${command}_ok
  • ☑️ Already compliant: command_execution_as_user_${command}_kept
  • 🟨 Repaired: command_execution_as_user_${command}_repaired
• ❌ Error: command_execution_as_user_${command}_error

Example

method: command_execution_as_user
params:
  user: VALUE
  command: VALUE

Documentation

Execute the Command in shell using a specific user.

On Unix based agents, the method status will report:

• a Repaired if the return code is "0"
• an Error if the return code is not "0"

command_execution_once

Execute a command only once on a node.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${command} with its actual canonified value.

• ✅ Ok: command_execution_once_${command}_ok
  • ☑️ Already compliant: command_execution_once_${command}_kept
  • 🟨 Repaired: command_execution_once_${command}_repaired
• ❌ Error: command_execution_once_${command}_error

Example

method: command_execution_once
params:
  command: VALUE
  ok_codes: OPTIONAL_VALUE
  unique_id: OPTIONAL_VALUE
  until: any

Documentation

This method is useful for specific commands that should only be executed once per node.

If you can spot a condition for the command execution by testing the state of its target, it is better to use the condition_from_command method to test the state coupled with the command_execution_result method to run the command if necessary.

In case of reinstallation or factory-reset of the Rudder agent, this method will no longer detect if a command has already been executed.

The method will:

Define the command_execution_once_${command}_kept condition and do nothing if a command_execution_once has already been executed on this machine with the same Unique id.

Execute the command if it is the first occurrence and:

• If the parameter Until is *any*, it will consider the command as executed on the machine and define either:
  • command_execution_once_${command}_repaired if the return code is in ok_codes,
  • command_execution_once_${command}_error otherwise.
• If the parameter Until is ok and:
  • If the return code is in the Ok codes list, define the command_execution_once_${command}_repaired condition
  • If the return code is not in Ok codes it define the command_execution_once_${command}_error condition and retry at next agent run.

If an exit code is not in the list it will lead to an error status. If you want "0" to be a success you have to list it in the Ok codes list

Example:

If you use:

    command_execution_once("command -a -t", "0", "ok", "my_program_setup")

It will retry to run command -a -t until it returns "0". Then it will not execute it again.

command_execution_result

Execute a command and create result conditions depending on its exit code.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${command} with its actual canonified value.

• ✅ Ok: command_execution_result_${command}_ok
  • ☑️ Already compliant: command_execution_result_${command}_kept
  • 🟨 Repaired: command_execution_result_${command}_repaired
• ❌ Error: command_execution_result_${command}_error

Example

method: command_execution_result
params:
  repaired_codes: VALUE
  kept_codes: VALUE
  command: VALUE

Documentation

Execute a command and create result conditions depending on the exit codes given in parameters. If an exit code is not in the list it will lead to an error status. If you want 0 to be a success you have to list it in the kept_codes list

condition_from_command

Execute a command and create result conditions depending on its exit code.

⚙️ Compatible targets: Linux, Windows

Parameters

Outcome conditions

You need to replace ${condition} with its actual canonified value.

• ✅ Ok: condition_from_command_${condition}_ok
  • ☑️ Already compliant: condition_from_command_${condition}_kept
  • 🟨 Repaired: condition_from_command_${condition}_repaired
• ❌ Error: condition_from_command_${condition}_error

Example

method: condition_from_command
params:
  true_codes: VALUE
  condition: VALUE
  command: VALUE
  false_codes: VALUE

Documentation

This method executes a command, and defines a ${condition}_true or a ${condition}_false condition depending on the result of the command:

• If the exit code is in the "True codes" list, this will produce a kept outcome and a ${condition}_true condition,
• If the exit code is in the "False codes" list, this will produce a kept outcome and a ${condition}_false condition,
• If the exit code is not in "True codes" nor in "False codes", or if the command can not be found, it will produce an error outcome and and no condition from ${condition}

The created condition is global to the agent.

Windows

On Windows nodes, the exit code is taken from the LASTEXITCODE which is defined either by:

• The exit code of a binary execution (when the command a call to an exe)
• The return code of a Powershell script

Direct Powershell execution will almost always return 0 as LASTEXITCODE value, meaning that you have to execute either a binary or a Powershell script to control the return code.

Example:

If you run a command /bin/check_network_status that output code 0, 1 or 2 in case of correct configuration, and 18 or 52 in case of invalid configuration, and you want to define a condition based on its execution result, you can use:

condition_from_command("network_correctly_defined", "/bin/check_network_status", "0,1,2", "18,52")

• If the command exits with 0, 1 or 2, then it will define the conditions

  • network_correctly_defined_true,
  • condition_from_command_network_correctly_defined_kept,
  • condition_from_command_network_correctly_defined_reached,

• If the command exits 18, 52, then it will define the conditions

  • network_correctly_defined_false,
  • condition_from_command_network_correctly_defined_kept,
  • condition_from_command_network_correctly_defined_reached

• If the command exits any other code or is not found, then it will define the conditions

  • condition_from_command_network_correctly_defined_error,
  • condition_from_command_network_correctly_defined_reached

Notes:

• In audit mode, this method will still execute the command passed in parameter. Which means that you should only pass non system-impacting commands to this method.

• Rudder will automatically "canonify" the given Condition prefix at execution time, which means that all non [a-zA-Z0-9_] characters will be replaced by an underscore.

condition_from_expression

Create a new condition.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${condition} with its actual canonified value.

• ✅ Ok: condition_from_expression_${condition}_ok
  • ☑️ Already compliant: condition_from_expression_${condition}_kept
  • 🟨 Repaired: condition_from_expression_${condition}_repaired
• ❌ Error: condition_from_expression_${condition}_error

Example

method: condition_from_expression
params:
  condition: VALUE
  expression: VALUE

Documentation

This method evaluates an expression, and produces a ${condition}_true or a ${condition}_false condition depending on the result of the expression evaluation:

• This method always result with a success outcome status
• If the evaluation results in a "defined" state, this will define a ${condition}_true condition,
• If the evaluation results in an "undefined" state, this will produce a ${condition}_false condition.

Calling this method with a condition expression transforms a complex expression into a single condition.

The created condition is global to the agent.

Example

If you want to check if a condition evaluates to true, like checking that you are on Monday, 2am, on RedHat systems, you can use the following policy

condition_from_expression("backup_time", "Monday.redhat.Hr02")

The method will define:

• In any case:
  • condition_from_expression_backup_time_kept
  • condition_from_expression_backup_time_reached
• And:
  • backup_time_true if the system is a RedHat like system, on Monday, at 2am.
  • backup_time_false if the system not a RedHat like system, or it's not Monday, or it's not 2am
  • no extra condition if the expression is invalid (cannot be parsed)

Notes:

Rudder will automatically "canonify" the given Condition prefix at execution time, which means that all non [a-zA-Z0-9_] characters will be replaced by an underscore.

condition_from_expression_persistent

Create a new condition that persists across runs.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${condition} with its actual canonified value.

• ✅ Ok: condition_from_expression_persistent_${condition}_ok
  • ☑️ Already compliant: condition_from_expression_persistent_${condition}_kept
  • 🟨 Repaired: condition_from_expression_persistent_${condition}_repaired
• ❌ Error: condition_from_expression_persistent_${condition}_error

Example

method: condition_from_expression_persistent
params:
  duration: VALUE
  condition: VALUE
  expression: VALUE

Documentation

This method evaluates an expression (=condition combination), and produces a ${condition}_true or a ${condition}_false condition depending on the result on the expression, which will lasts for the Duration time:

• This method always result with a success outcome status
• If the expression evaluation results in a "defined" state, this will define a ${condition}_true condition,
• If the expression evaluation results in an "undefined" state, this will produce a ${condition}_false condition.

Calling this method with a condition expression transforms a complex expression into a single class condition.

The created condition is global to the agent and is persisted across runs. The persistence duration is controlled using the parameter Duration which defines for how long the target condition will be defined (in minutes). Note that there is no way to persist indefinitely.

Example:

If you want to check if a condition evaluates to true, like checking that you are on Monday, 2am, on RedHat systems, and make it last one hour you can use the following policy

condition_from_expression_persistent_("backup_time", "Monday.redhat.Hr02", "60")

The method will define:

• In any case:
  • condition_from_expression_persistent_backup_time_kept
  • condition_from_expression_persistent_backup_time_reached
• And:
  • backup_time_true if the system is a RedHat like system, on Monday, at 2am, and will persist for Duration minutes,
  • backup_time_false if the system not a RedHat like system, or it's not Monday, or it's not 2am
  • no extra condition if the expression is invalid (cannot be parsed)

Notes:

Rudder will automatically "canonify" the given Condition prefix at execution time, which means that all non [a-zA-Z0-9_] characters will be replaced by an underscore.

condition_from_string_match

Test the content of a string variable.

⚙️ Compatible targets: Linux, Windows

Parameters

Outcome conditions

You need to replace ${condition} with its actual canonified value.

• ✅ Ok: condition_from_string_match_${condition}_ok
  • ☑️ Already compliant: condition_from_string_match_${condition}_kept
  • 🟨 Repaired: condition_from_string_match_${condition}_repaired
• ❌ Error: condition_from_string_match_${condition}_error

Example

method: condition_from_string_match
params:
  value: VALUE
  regex: VALUE
  condition: VALUE

Documentation

Test a string against a regex pattern and create conditions depending on the match result:

• ${condition}_true condition is defined if the regex matches
• ${condition}_false condition is defined if the regex does not match the string

The regex is singleline, case sensitive, culture invariant and implicitly enclosed by the start/end of string delimiters ^ and $. This method's reporting status will always be "success".

Examples

-name: Define is_matching_true
 method: condition_from_string_match
 params:
   condition: is_matching
   value: "Some\nmulti\nline\ntext"
   regex: "Some.*text"

condition_from_variable_existence

Create a condition from the existence of a variable.

⚙️ Compatible targets: Linux, Windows

Parameters

Outcome conditions

You need to replace ${condition} with its actual canonified value.

• ✅ Ok: condition_from_variable_existence_${condition}_ok
  • ☑️ Already compliant: condition_from_variable_existence_${condition}_kept
  • 🟨 Repaired: condition_from_variable_existence_${condition}_repaired
• ❌ Error: condition_from_variable_existence_${condition}_error

Example

method: condition_from_variable_existence
params:
  condition: VALUE
  variable_name: VALUE

Documentation

This method define a condition:

• {condition}_true if the variable named from the parameter Variable name is defined
• {condition}_false if the variable named from the parameter Variable name is not defined

Also, this method always result with a success outcome status.

condition_from_variable_match

Test the content of a string variable.

⚙️ Compatible targets: Linux, Windows

Parameters

Outcome conditions

You need to replace ${condition} with its actual canonified value.

• ✅ Ok: condition_from_variable_match_${condition}_ok
  • ☑️ Already compliant: condition_from_variable_match_${condition}_kept
  • 🟨 Repaired: condition_from_variable_match_${condition}_repaired
• ❌ Error: condition_from_variable_match_${condition}_error

Example

method: condition_from_variable_match
params:
  condition: VALUE
  variable_name: VALUE
  expected_match: VALUE

Documentation

Test a string variable content and create conditions depending on its value:

• If the variable is found and its content matches the given regex:
  • a ${condition}_true condition,
  • and kept outcome status
• If the variable is found but its content does not match the given regex:
  • a ${condition}_false condition,
  • and a kept outcome status
• If the variable can not be found:
  • a ${condition}_false condition
  • and an error outcome status

Be careful, we are using variable name not the value. For example if you want to match the property value "foo" you will just need node.properties[foo] without ${...} syntax

/!\ Regex for unix machine must be PCRE compatible and those for Windows agent must respect the .Net regex format.

• If you want to test a technique parameter, use the technique_id of the technique as variable prefix and theparameter_name as variable name.

The method only supports plain string type variables.

condition_once

Create a new condition only once.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${condition} with its actual canonified value.

• ✅ Ok: condition_once_${condition}_ok
  • ☑️ Already compliant: condition_once_${condition}_kept
  • 🟨 Repaired: condition_once_${condition}_repaired
• ❌ Error: condition_once_${condition}_error

Example

method: condition_once
params:
  condition: VALUE

Documentation

This method define a condition named from the parameter Condition when it is called for the first time. Following agent execution will not define the condition.

This allows executing actions only once on a given machine. The created condition is global to the agent.

In case of reinstallation or factory-reset of the Rudder agent, this method will no longer detect if the condition has already been defined.

Example:

If you use:

condition_once("my_condition")

The first agent run will have the condition my_condition defined, contrary to subsequent runs for which no condition will be defined.

See also : command_execution_once

directory_absent

Ensure a directory's absence.

⚙️ Compatible targets: Linux, Windows

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: directory_absent_${path}_ok
  • ☑️ Already compliant: directory_absent_${path}_kept
  • 🟨 Repaired: directory_absent_${path}_repaired
• ❌ Error: directory_absent_${path}_error

Example

method: directory_absent
params:
  recursive: OPTIONAL_VALUE
  path: VALUE

Documentation

If recursive is false, only an empty directory can be deleted.

directory_check_exists

Checks if a directory exists.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: directory_check_exists_${path}_ok
  • ☑️ Already compliant: directory_check_exists_${path}_kept
  • 🟨 Repaired: directory_check_exists_${path}_repaired
• ❌ Error: directory_check_exists_${path}_error

Example

method: directory_check_exists
params:
  path: VALUE

Documentation

This bundle will define a condition directory_check_exists_${path}_{ok, reached, kept} if the directory exists, or directory_check_exists_${path}_{not_ok, reached, not_kept, failed} if the directory doesn't exists

directory_create

Create a directory if it doesn't exist.

⚙️ Compatible targets: Linux, Windows

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: directory_create_${path}_ok
  • ☑️ Already compliant: directory_create_${path}_kept
  • 🟨 Repaired: directory_create_${path}_repaired
• ❌ Error: directory_create_${path}_error

Example

method: directory_create
params:
  path: VALUE

directory_present

Create a directory if it doesn't exist.

⚙️ Compatible targets: Linux, Windows

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: directory_present_${path}_ok
  • ☑️ Already compliant: directory_present_${path}_kept
  • 🟨 Repaired: directory_present_${path}_repaired
• ❌ Error: directory_present_${path}_error

Example

method: directory_present
params:
  path: VALUE

Documentation

Create a directory if it doesn't exist.

dsc_apply

Ensure that all MOF files under MOFFile are applied via DSC.

⚙️ Compatible targets: Windows

Parameters

Outcome conditions

You need to replace ${MOFFile} with its actual canonified value.

• ✅ Ok: dsc_apply_${MOFFile}_ok
  • ☑️ Already compliant: dsc_apply_${MOFFile}_kept
  • 🟨 Repaired: dsc_apply_${MOFFile}_repaired
• ❌ Error: dsc_apply_${MOFFile}_error

Example

method: dsc_apply
params:
  MOFFile: VALUE

Documentation

Ensure that all MOF files contained under the target folder are applied via DSC on the target node.

dsc_built_in_resource

This generic method defines if service should run or be stopped.

⚙️ Compatible targets: Windows

Parameters

Outcome conditions

You need to replace ${tag} with its actual canonified value.

• ✅ Ok: dsc_built_in_resource_${tag}_ok
  • ☑️ Already compliant: dsc_built_in_resource_${tag}_kept
  • 🟨 Repaired: dsc_built_in_resource_${tag}_repaired
• ❌ Error: dsc_built_in_resource_${tag}_error

Example

method: dsc_built_in_resource
params:
  tag: VALUE
  resourceName: VALUE
  scriptBlock: VALUE

Documentation

Apply a given DSC resource to the node.

Parameters

• tag parameter is purely informative and has no impact on the resource.
• ResourceName must be the explicit name of the DSC resource you wish to apply
• ScriptBlock must be a powershell script in plain text, returning an Hashtable containing the parameters to pass to the resource.

Note that this method can only apply built-in Windows resources. It will not be able to apply an external resource.

Example

If we want to apply a Registry resource. The resourceName used will be Registry And a potential ScriptBlock could be:

 $HKLM_SOFT="HKEY_LOCAL_MACHINE\SOFTWARE"
 $Ensure      = "Present"
 $Key         = $HKLM_SOFT + "\ExampleKey"

 $table = @{}
 $table.Add("Ensure", $Ensure)
 $table.Add("Key", $Key)
 $table.Add("ValueName", "RudderTest")
 $table.Add("ValueData", "TestData")
 $table

Note that all the ScriptBlock will be readable on the Rudder logs or in the policy files.

dsc_from_configuration

Compile and apply a given DSC configuration defined by a ps1 file.

⚙️ Compatible targets: Windows

Parameters

Outcome conditions

You need to replace ${tag} with its actual canonified value.

• ✅ Ok: dsc_from_configuration_${tag}_ok
  • ☑️ Already compliant: dsc_from_configuration_${tag}_kept
  • 🟨 Repaired: dsc_from_configuration_${tag}_repaired
• ❌ Error: dsc_from_configuration_${tag}_error

Example

method: dsc_from_configuration
params:
  tag: VALUE
  config_file: VALUE

Documentation

Compile and apply a given DSC configuration. The DSC configuration must be defined within a .ps1 file, and is expected to be "self compilable". A configuration data file (.psd1) containing variables can also be referenced by the ps1 script, by referring to it in the Configuration call.

The method will try to compile the configuration whenever the policies of the nodes are updated of if the previous compilation did not succeed.

All the Rudder variables are usable in your configuration.

Also the current method only allows DSC configurations to be run on the localhost target node, and when using a DSC push setup. Note that it may conflict with already existing DSC configurations not handled by Rudder.

Example 1 - without external data

Here is a configuration named EnsureWebServer.ps1 with simple Windows feature management:

Configuration EnsureWebServer {
 Node 'localhost' {
   # Install the IIS role
   WindowsFeature IIS {
       Ensure       = 'Present'
       Name         = 'Web-Server'
   }

   # Install the ASP .NET 4.5 role
   WindowsFeature AspNet45 {
       Ensure       = 'Present'
       Name         = 'Web-Asp-Net45'
   }
 }
}

EnsureWebServer

Example 2 with external data

Dsc configurations can be fed with external data, here is an example using a datafile Data.psd1 containing:

 @{
     AllNodes = @();
     NonNodeData =
     @{
       ConfigFileContents = "Hello World! This file is managed by Rudder"
     }
 }

Used to feed the HelloWorld.ps1 Contents key:

Configuration HelloWorld {
  Import-DscResource -ModuleName 'PSDesiredStateConfiguration'

  Node 'localhost' {
    File HelloWorld {
        DestinationPath = "${RudderBase}\HelloWorld.txt"
        Ensure          = "Present"
        Contents        = $ConfigurationData.NonNodeData.ConfigFileContents
    }
  }
}

HelloWorld -ConfigurationData /path/to/Data.psd1

Please note that the reference to the data file is done inside the configuration file.

dsc_mof_file_apply

Ensure that all MOF files under MOFFile are applied via DSC.

⚙️ Compatible targets: Windows

Parameters

Outcome conditions

You need to replace ${MOFFile} with its actual canonified value.

• ✅ Ok: dsc_mof_file_apply_${MOFFile}_ok
  • ☑️ Already compliant: dsc_mof_file_apply_${MOFFile}_kept
  • 🟨 Repaired: dsc_mof_file_apply_${MOFFile}_repaired
• ❌ Error: dsc_mof_file_apply_${MOFFile}_error

Example

method: dsc_mof_file_apply
params:
  MOFFile: VALUE

Documentation

Ensure that all MOF files contained under the target folder are applied via DSC on the target node.

environment_variable_present

Enforce an environment variable value.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${name} with its actual canonified value.

• ✅ Ok: environment_variable_present_${name}_ok
  • ☑️ Already compliant: environment_variable_present_${name}_kept
  • 🟨 Repaired: environment_variable_present_${name}_repaired
• ❌ Error: environment_variable_present_${name}_error

Example

method: environment_variable_present
params:
  value: VALUE
  name: VALUE

Documentation

Force the value of a shell environment variable. The variable will be written in /etc/environment. A newly created environment variable will not be usable by the agent until it is restarted.

file_absent

Remove a file if it exists.

⚙️ Compatible targets: Linux, Windows

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_absent_${path}_ok
  • ☑️ Already compliant: file_absent_${path}_kept
  • 🟨 Repaired: file_absent_${path}_repaired
• ❌ Error: file_absent_${path}_error

Example

method: file_absent
params:
  path: VALUE

file_augeas_commands

Use Augeas binaries to execute augtool commands and options directly on the agent.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${variable_name} with its actual canonified value.

• ✅ Ok: file_augeas_commands_${variable_name}_ok
  • ☑️ Already compliant: file_augeas_commands_${variable_name}_kept
  • 🟨 Repaired: file_augeas_commands_${variable_name}_repaired
• ❌ Error: file_augeas_commands_${variable_name}_error

Example

method: file_augeas_commands
params:
  autoload: 'true'
  commands: VALUE
  variable_name: VALUE
  variable_prefix: VALUE

Documentation

Augeas is a tool that provides an abstraction layer for all the complexities that turn around editing files with regular expressions.

This method defines a rudder variable from the output of a augtool command. The method has in total 4 parameters:

• variable_prefix: target variable prefix
• variable_name: target variable name
• commands: augtool script to run
• autoload: boolean to load or not the common augeas lens, default to true

Augtool provides bunch of other commands and options that you can use in this generic method such as match to print the matches for a specific path expression, span to print position in input file corresponding to tree, retrieve to transform tree into text and save to save all pending changes. If Augeas isn't installed on the agent, it will produces an error.

This method will execute the commands via augtool. The particular thing you may want to do with this method is using it depending on you needs and in two cases.

With autoload

Augeas will accordingly load all files and lenses before executing the commands you have specified since autoload is active.

file_augeas_commands("label","value","print /files/etc/hosts/*/ipaddr[../canonical="server.rudder.local"]","")
# The variable label.value will be defined as such:
${label.value} -> /files/etc/hosts/2/ipaddr = "192.168.2.2"

file_augeas_commands("label","value","ls files/etc/ \n print /files/etc/ssh/sshd_config","true")
# Will define the variable label.value with the list of files availables in /etc and already parsable with augeas,
# followed by the dump of the sshd_config file, parsed by augeas.

Without autoload

The second case is when you deactivate that option which means that you are specifying autoload to false and in this case you have to load manually your files and lenses in the commands parameter by using the set augeas command. Below is a second example where the lens and file are explicitly set:

file_augeas_commands("label","value","set /augeas/load/Sshd/lens "Sshd.lns \n set /augeas/load/Sshd/incl "/etc/ssh/sshd_config" \n load \n print /augeas/load/Sshd \n print /augeas/load/Sshd \n print /files/etc/ssh/sshd_config","false")

file_augeas_set

Use augeas commands and options to set a node label's value.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_augeas_set_${path}_ok
  • ☑️ Already compliant: file_augeas_set_${path}_kept
  • 🟨 Repaired: file_augeas_set_${path}_repaired
• ❌ Error: file_augeas_set_${path}_error

Example

method: file_augeas_set
params:
  lens: OPTIONAL_VALUE
  path: VALUE
  file: OPTIONAL_VALUE
  value: VALUE

Documentation

Augeas is a tool that provides an abstraction layer for all the complexities that turn around editing files with regular expressions. It's a tree based hierarchy tool, that handles system configuration files where you can securely modify your files and to do so you have to provide the path to the node label's value.

Augeas uses lenses which are like sort of modules that are in charge of identifying and converting files into tree and back.

This method uses augtool to force the value of an augeas node's label.

Actually there are two ways to use this method:

• Either by providing the augeas path to the node's label and let lens and file empty. ** this way augeas will load the common files and lens automatically
• Or by using a given file path and a specific lens. ** better performances since only one lens is loaded ** support custom lens, custom paths (for instance to apply the Hosts lens to another file than /etc/hosts)
• Either by simply providing an augeas path to the node's label

Warning: When you don't specify the file and lens to use, no backup of the file will be made before editing it.

Two uses cases examples:

In the first case, let's suppose that you want to set the value of the ip address of the first line in the /etc/hosts file to 192.168.1.5, to do so you need to provide the augeas path and value parameters.

file_augeas_set("/etc/hosts/1/ipaddr", "192.168.1.5", "", "");

The second case is more efficient, and forces the Hosts lens to parse the /etc/hosts file and set the value for the given path node:

file_augeas_set("/etc/hosts/1/ipaddr", "192.168.1.5", "Hosts", "/etc/hosts");

file_block_present

Ensure that a text block is present in a specific location.

⚙️ Compatible targets: Linux, Windows

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_block_present_${path}_ok
  • ☑️ Already compliant: file_block_present_${path}_kept
  • 🟨 Repaired: file_block_present_${path}_repaired
• ❌ Error: file_block_present_${path}_error

Example

method: file_block_present
params:
  path: VALUE
  block: VALUE

Documentation

Ensure that a text block is present in the target file. If the block is not found, it will be added at the end of the file.

Examples:

Given a file with the following content:

apple
pear
banana

Applying the method with the block:

pear
orange

Will result in the following content:

apple
pear
banana
pear
orange

file_block_present_in_section

Ensure that a section contains exactly a text block.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_block_present_in_section_${path}_ok
  • ☑️ Already compliant: file_block_present_in_section_${path}_kept
  • 🟨 Repaired: file_block_present_in_section_${path}_repaired
• ❌ Error: file_block_present_in_section_${path}_error

Example

method: file_block_present_in_section
params:
  section_end: VALUE
  path: VALUE
  block: VALUE
  section_start: VALUE

Documentation

Ensure that a section contains exactly a text block. A section is delimited by a header and a footer.

• If the section exists, its content will be replaced if needed
• Otherwise it will be created at the end of the file

file_check_FIFO_pipe

Checks if a file exists and is a FIFO/Pipe.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_check_FIFO_pipe_${path}_ok
  • ☑️ Already compliant: file_check_FIFO_pipe_${path}_kept
  • 🟨 Repaired: file_check_FIFO_pipe_${path}_repaired
• ❌ Error: file_check_FIFO_pipe_${path}_error

Example

method: file_check_FIFO_pipe
params:
  path: VALUE

Documentation

This bundle will define a condition file_check_FIFO_pipe_${path}_{ok, reached, kept} if the file is a FIFO, or file_check_FIFO_pipe_${path}_{not_ok, reached, not_kept, failed} if the file is not a fifo or does not exist

file_check_block_device

Checks if a file exists and is a block device.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_check_block_device_${path}_ok
  • ☑️ Already compliant: file_check_block_device_${path}_kept
  • 🟨 Repaired: file_check_block_device_${path}_repaired
• ❌ Error: file_check_block_device_${path}_error

Example

method: file_check_block_device
params:
  path: VALUE

Documentation

This bundle will define a condition file_check_block_device_${path}_{ok, reached, kept} if the file is a block_device, or file_check_block_device_${path}_{not_ok, reached, not_kept, failed} if the file is not a block device or does not exist

file_check_character_device

Checks if a file exists and is a character device.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_check_character_device_${path}_ok
  • ☑️ Already compliant: file_check_character_device_${path}_kept
  • 🟨 Repaired: file_check_character_device_${path}_repaired
• ❌ Error: file_check_character_device_${path}_error

Example

method: file_check_character_device
params:
  path: VALUE

Documentation

This bundle will define a condition file_check_character_device_${path}_{ok, reached, kept} if the file is a character device, or file_check_character_device_${path}_{not_ok, reached, not_kept, failed} if the file is not a character device or does not exist

file_check_exists

Checks if a file exists.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_check_exists_${path}_ok
  • ☑️ Already compliant: file_check_exists_${path}_kept
  • 🟨 Repaired: file_check_exists_${path}_repaired
• ❌ Error: file_check_exists_${path}_error

Example

method: file_check_exists
params:
  path: VALUE

Documentation

This bundle will define a condition file_check_exists_${path}_{ok, reached, kept} if the file exists, or file_check_exists_${path}_{not_ok, reached, not_kept, failed} if the file doesn't exists

file_check_hardlink

Checks if two files are the same (hard links).

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_check_hardlink_${path}_ok
  • ☑️ Already compliant: file_check_hardlink_${path}_kept
  • 🟨 Repaired: file_check_hardlink_${path}_repaired
• ❌ Error: file_check_hardlink_${path}_error

Example

method: file_check_hardlink
params:
  path: VALUE
  path_2: VALUE

Documentation

This bundle will define a condition file_check_hardlink_${path}_{ok, reached, kept} if the two files ${path} and ${path_2} are hard links of each other, or file_check_hardlink_${path}_{not_ok, reached, not_kept, failed} if if the files are not hard links.

file_check_regular

Checks if a file exists and is a regular file.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_check_regular_${path}_ok
  • ☑️ Already compliant: file_check_regular_${path}_kept
  • 🟨 Repaired: file_check_regular_${path}_repaired
• ❌ Error: file_check_regular_${path}_error

Example

method: file_check_regular
params:
  path: VALUE

Documentation

This bundle will define a condition file_check_regular_${path}_{ok, reached, kept} if the file is a regular_file, or file_check_regular_${path}_{not_ok, reached, not_kept, failed} if the file is not a regular file or does not exist

file_check_socket

Checks if a file exists and is a socket.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_check_socket_${path}_ok
  • ☑️ Already compliant: file_check_socket_${path}_kept
  • 🟨 Repaired: file_check_socket_${path}_repaired
• ❌ Error: file_check_socket_${path}_error

Example

method: file_check_socket
params:
  path: VALUE

Documentation

This bundle will define a condition file_check_socket_${path}_{ok, reached, kept} if the file is a socket, or file_check_socket_${path}_{not_ok, reached, not_kept, failed} if the file is not a socket or does not exist

file_check_symlink

Checks if a file exists and is a symlink.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_check_symlink_${path}_ok
  • ☑️ Already compliant: file_check_symlink_${path}_kept
  • 🟨 Repaired: file_check_symlink_${path}_repaired
• ❌ Error: file_check_symlink_${path}_error

Example

method: file_check_symlink
params:
  path: VALUE

Documentation

This bundle will define a condition file_check_symlink_${path}_{ok, reached, kept} if the file is a symlink, or file_check_symlink_${path}_{not_ok, reached, not_kept, failed} if the file is not a symlink or does not exist

file_check_symlinkto

Checks if first file is symlink to second file.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_check_symlinkto_${path}_ok
  • ☑️ Already compliant: file_check_symlinkto_${path}_kept
  • 🟨 Repaired: file_check_symlinkto_${path}_repaired
• ❌ Error: file_check_symlinkto_${path}_error

Example

method: file_check_symlinkto
params:
  target: VALUE
  path: VALUE

Documentation

This bundle will define a condition file_check_symlinkto_${target}_{ok, reached, kept} if the file ${path} is a symbolic link to ${target}, or file_check_symlinkto_${target}_{not_ok, reached, not_kept, failed} if if it is not a symbolic link, or any of the files does not exist. The symlink's path is resolved to the absolute path and checked against the target file's path, which must also be an absolute path.

file_content

Enforce the content of a file.

⚙️ Compatible targets: Linux, Windows

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_lines_present_${path}_ok
  • ☑️ Already compliant: file_lines_present_${path}_kept
  • 🟨 Repaired: file_lines_present_${path}_repaired
• ❌ Error: file_lines_present_${path}_error

Example

method: file_content
params:
  path: VALUE
  lines: VALUE
  enforce: 'true'

Documentation

Enforce the content of a file. The enforce parameter changes the edition method:

• If enforce is set to true the file content will be forced
• If enforce is set to false the file content will be forced line by line. Which means that each line managed can not be duplicated and the order will not be guaranteed.

In most cases, the enforce parameter should be set to true. When enforce is set to false, and the managed lines are:

Bob
Alice
Charly

Will be compliant with the following file contents:

Bob
Alice
Charly

Charly
Bob
Alice
Charly

Bob
Charly
Alice

file_copy_from_local_source

Ensure that a file or directory is copied from a local source.

⚙️ Compatible targets: Linux, Windows

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_copy_from_local_source_${path}_ok
  • ☑️ Already compliant: file_copy_from_local_source_${path}_kept
  • 🟨 Repaired: file_copy_from_local_source_${path}_repaired
• ❌ Error: file_copy_from_local_source_${path}_error

Example

method: file_copy_from_local_source
params:
  source: VALUE
  path: VALUE

file_copy_from_local_source_recursion

Ensure that a file or directory is copied from a local source.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_copy_from_local_source_${path}_ok
  • ☑️ Already compliant: file_copy_from_local_source_${path}_kept
  • 🟨 Repaired: file_copy_from_local_source_${path}_repaired
• ❌ Error: file_copy_from_local_source_${path}_error

Example

method: file_copy_from_local_source_recursion
params:
  source: VALUE
  path: VALUE
  recursion: VALUE

file_copy_from_local_source_with_check

Ensure that a file or directory is copied from a local source if a check command succeeds.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_copy_from_local_source_with_check_${path}_ok
  • ☑️ Already compliant: file_copy_from_local_source_with_check_${path}_kept
  • 🟨 Repaired: file_copy_from_local_source_with_check_${path}_repaired
• ❌ Error: file_copy_from_local_source_with_check_${path}_error

Example

method: file_copy_from_local_source_with_check
params:
  check_command: VALUE
  path: VALUE
  rc_ok: OPTIONAL_VALUE
  source: VALUE

Documentation

This method is a conditional file copy.

file_copy_from_remote_source

Ensure that a file or directory is copied from a policy server.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_copy_from_remote_source_${path}_ok
  • ☑️ Already compliant: file_copy_from_remote_source_${path}_kept
  • 🟨 Repaired: file_copy_from_remote_source_${path}_repaired
• ❌ Error: file_copy_from_remote_source_${path}_error

Example

method: file_copy_from_remote_source
params:
  path: VALUE
  source: VALUE

Documentation

Note: This method uses the native agent copy protocol, and can only download files from the policy server. To download a file from an external source, you can use HTTP with the file_download method.

This method requires that the policy server is configured to accept copy of the source file from the agents it will be applied to.

You can download a file from the shared files with:

/var/rudder/configuration-repository/shared-files/PATH_TO_YOUR_FILE

file_copy_from_remote_source_recursion

Ensure that a file or directory is copied from a policy server.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_copy_from_remote_source_${path}_ok
  • ☑️ Already compliant: file_copy_from_remote_source_${path}_kept
  • 🟨 Repaired: file_copy_from_remote_source_${path}_repaired
• ❌ Error: file_copy_from_remote_source_${path}_error

Example

method: file_copy_from_remote_source_recursion
params:
  recursion: VALUE
  source: VALUE
  path: VALUE

Documentation

This method requires that the policy server is configured to accept copy of the source file or directory from the agents it will be applied to.

You can download a file from the shared files with:

/var/rudder/configuration-repository/shared-files/PATH_TO_YOUR_DIRECTORY_OR_FILE

file_create

Create a file if it doesn't exist.

⚙️ Compatible targets: Linux, Windows

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_create_${path}_ok
  • ☑️ Already compliant: file_create_${path}_kept
  • 🟨 Repaired: file_create_${path}_repaired
• ❌ Error: file_create_${path}_error

Example

method: file_create
params:
  path: VALUE

file_create_symlink

Create a symlink at a destination path and pointing to a source target except if a file or directory already exists.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_create_symlink_${path}_ok
  • ☑️ Already compliant: file_create_symlink_${path}_kept
  • 🟨 Repaired: file_create_symlink_${path}_repaired
• ❌ Error: file_create_symlink_${path}_error

Example

method: file_create_symlink
params:
  path: VALUE
  source: VALUE

file_create_symlink_enforce

Create a symlink at a destination path and pointing to a source target. This is also possible to enforce its creation.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_create_symlink_${path}_ok
  • ☑️ Already compliant: file_create_symlink_${path}_kept
  • 🟨 Repaired: file_create_symlink_${path}_repaired
• ❌ Error: file_create_symlink_${path}_error

Example

method: file_create_symlink_enforce
params:
  path: VALUE
  source: VALUE
  enforce: VALUE

file_create_symlink_force

Create a symlink at a destination path and pointing to a source target even if a file or directory already exists.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_create_symlink_${path}_ok
  • ☑️ Already compliant: file_create_symlink_${path}_kept
  • 🟨 Repaired: file_create_symlink_${path}_repaired
• ❌ Error: file_create_symlink_${path}_error

Example

method: file_create_symlink_force
params:
  path: VALUE
  source: VALUE

file_download

Download a file if it does not exist, using curl with a fallback on wget.

⚙️ Compatible targets: Linux, Windows

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_download_${path}_ok
  • ☑️ Already compliant: file_download_${path}_kept
  • 🟨 Repaired: file_download_${path}_repaired
• ❌ Error: file_download_${path}_error

Example

method: file_download
params:
  source: VALUE
  path: VALUE

Documentation

This method finds a HTTP command-line tool and downloads the given source into the destination.

It tries curl first, and wget as fallback.

file_enforce_content

Enforce the content of a file.

⚙️ Compatible targets: Linux, Windows

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_ensure_lines_present_${path}_ok
  • ☑️ Already compliant: file_ensure_lines_present_${path}_kept
  • 🟨 Repaired: file_ensure_lines_present_${path}_repaired
• ❌ Error: file_ensure_lines_present_${path}_error

Example

method: file_enforce_content
params:
  path: VALUE
  lines: VALUE
  enforce: VALUE

file_ensure_block_in_section

Ensure that a section contains exactly a text block.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_ensure_block_in_section_${path}_ok
  • ☑️ Already compliant: file_ensure_block_in_section_${path}_kept
  • 🟨 Repaired: file_ensure_block_in_section_${path}_repaired
• ❌ Error: file_ensure_block_in_section_${path}_error

Example

method: file_ensure_block_in_section
params:
  section_start: VALUE
  section_end: VALUE
  block: VALUE
  path: VALUE

file_ensure_block_present

Ensure that a text block is present in a specific location.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_ensure_block_present_${path}_ok
  • ☑️ Already compliant: file_ensure_block_present_${path}_kept
  • 🟨 Repaired: file_ensure_block_present_${path}_repaired
• ❌ Error: file_ensure_block_present_${path}_error

Example

method: file_ensure_block_present
params:
  path: VALUE
  block: VALUE

file_ensure_key_value

Ensure that the file contains a pair of "key separator value".

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_ensure_key_value_${path}_ok
  • ☑️ Already compliant: file_ensure_key_value_${path}_kept
  • 🟨 Repaired: file_ensure_key_value_${path}_repaired
• ❌ Error: file_ensure_key_value_${path}_error

Example

method: file_ensure_key_value
params:
  separator: VALUE
  value: VALUE
  path: VALUE
  key: VALUE

Documentation

Edit (or create) the file, and ensure it contains an entry key -> value with arbitrary separator between the key and its value. If the key is already present, the method will change the value associated with this key.

file_ensure_key_value_option

Ensure that the file contains a pair of "key separator value", with options on the spacing around the separator.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_ensure_key_value_${path}_ok
  • ☑️ Already compliant: file_ensure_key_value_${path}_kept
  • 🟨 Repaired: file_ensure_key_value_${path}_repaired
• ❌ Error: file_ensure_key_value_${path}_error

Example

method: file_ensure_key_value_option
params:
  value: VALUE
  path: VALUE
  separator: VALUE
  key: VALUE
  option: strict

Documentation

Edit (or create) the file, and ensure it contains an entry key -> value with arbitrary separator between the key and its value. If the key is already present, the method will change the value associated with this key.

file_ensure_key_value_parameter_in_list

Ensure that one parameter exists in a list of parameters, on one single line, in the right hand side of a key->values line.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_ensure_key_value_parameter_in_list_${path}_ok
  • ☑️ Already compliant: file_ensure_key_value_parameter_in_list_${path}_kept
  • 🟨 Repaired: file_ensure_key_value_parameter_in_list_${path}_repaired
• ❌ Error: file_ensure_key_value_parameter_in_list_${path}_error

Example

method: file_ensure_key_value_parameter_in_list
params:
  parameter_separator: VALUE
  path: VALUE
  key_value_separator: VALUE
  parameter: VALUE
  key: VALUE
  closing_char_separator: OPTIONAL_VALUE
  leading_char_separator: OPTIONAL_VALUE

Documentation

Edit the file, and ensure it contains the defined parameter in the list of values on the right hand side of a key->values line. If the parameter is not there, it will be added at the end, separated by parameter_separator. Optionally, you can define leading and closing character to enclose the parameters If the key does not exist in the file, it will be added in the file, along with the parameter

Example

If you have an initial file (/etc/default/grub) containing

GRUB_CMDLINE_XEN="dom0_mem=16G"

To add parameter dom0_max_vcpus=32 in the right hand side of the line, you'll need the following policy

file_ensure_key_value_parameter_in_list("/etc/default/grub", "GRUB_CMDLINE", "=", "dom0_max_vcpus=32", " ", "\"", "\"");

file_ensure_key_value_parameter_not_in_list

Ensure that a parameter doesn't exist in a list of parameters, on one single line, in the right hand side of a key->values line.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_ensure_key_value_parameter_not_in_list_${path}_ok
  • ☑️ Already compliant: file_ensure_key_value_parameter_not_in_list_${path}_kept
  • 🟨 Repaired: file_ensure_key_value_parameter_not_in_list_${path}_repaired
• ❌ Error: file_ensure_key_value_parameter_not_in_list_${path}_error

Example

method: file_ensure_key_value_parameter_not_in_list
params:
  key: VALUE
  leading_char_separator: OPTIONAL_VALUE
  closing_char_separator: OPTIONAL_VALUE
  key_value_separator: VALUE
  parameter_separator: VALUE
  path: VALUE
  parameter_regex: VALUE

Documentation

Edit the file, and ensure it does not contain the defined parameter in the list of values on the right hand side of a key->values line. If the parameter is there, it will be removed. Please note that the parameter can be a regular expression. It will also remove any whitespace character between the parameter and parameter_separator Optionally, you can define leading and closing character to enclose the parameters

Example

If you have an initial file (/etc/default/grub) containing

GRUB_CMDLINE_XEN="dom0_mem=16G dom0_max_vcpus=32"

To remove parameter dom0_max_vcpus=32 in the right hand side of the line, you'll need the following policy

file_ensure_key_value_parameter_not_in_list("/etc/default/grub", "GRUB_CMDLINE", "=", "dom0_max_vcpus=32", " ", "\"", "\"");

file_ensure_key_value_present_in_ini_section

Ensure that a key-value pair is present in a section in a specific location. The objective of this method is to handle INI-style files.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_ensure_key_value_present_in_ini_section_${path}_ok
  • ☑️ Already compliant: file_ensure_key_value_present_in_ini_section_${path}_kept
  • 🟨 Repaired: file_ensure_key_value_present_in_ini_section_${path}_repaired
• ❌ Error: file_ensure_key_value_present_in_ini_section_${path}_error

Example

method: file_ensure_key_value_present_in_ini_section
params:
  name: VALUE
  section: VALUE
  path: VALUE
  value: VALUE

file_ensure_keys_values

Ensure that the file contains all pairs of "key separator value", with arbitrary separator between each key and its value.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_ensure_keys_values_${path}_ok
  • ☑️ Already compliant: file_ensure_keys_values_${path}_kept
  • 🟨 Repaired: file_ensure_keys_values_${path}_repaired
• ❌ Error: file_ensure_keys_values_${path}_error

Example

method: file_ensure_keys_values
params:
  path: VALUE
  separator: VALUE
  keys: VALUE

Documentation

This method ensures key-value pairs are present in a file.

Usage

This method will iterate over the key-value pairs in the dict, and:

• If the key is not defined in the destination, add the key + separator + value line.
• If the key is already present in the file, replace the key + separator + anything by key + separator + value

This method always ignores spaces and tabs when replacing (which means for example that key = value will match the = separator).

Keys are considered unique (to allow replacing the value), so you should use file_ensure_lines_present if you want to have multiple lines with the same key.

Example

If you have an initial file (/etc/myfile.conf) containing:

key1 = something
key3 = value3

To define key-value pairs, use the variable_dict or variable_dict_from_file methods.

For example, if you use the following content (stored in /tmp/data.json):

{
   "key1": "value1",
   "key2": "value2"
}

With the following policy:

# Define the `content` variable in the `configuration` prefix from the json file
variable_dict_from_file("configuration", "content", "/tmp/data.json")
# Enforce the presence of the key-value pairs
file_ensure_keys_values("/etc/myfile.conf", "configuration.content", " = ")

The destination file (/etc/myfile.conf) will contain:

key1 = value1
key3 = value3
key2 = value2

file_ensure_line_present_in_ini_section

Ensure that a line is present in a section in a specific location. The objective of this method is to handle INI-style files.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_ensure_line_present_in_ini_section_${path}_ok
  • ☑️ Already compliant: file_ensure_line_present_in_ini_section_${path}_kept
  • 🟨 Repaired: file_ensure_line_present_in_ini_section_${path}_repaired
• ❌ Error: file_ensure_line_present_in_ini_section_${path}_error

Example

method: file_ensure_line_present_in_ini_section
params:
  section: VALUE
  line: VALUE
  path: VALUE

file_ensure_line_present_in_xml_tag

Ensure that a line is present in a tag in a specific location. The objective of this method is to handle XML-style files. Note that if the tag is not present in the file, it won't be added, and the edition will fail.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_ensure_line_present_in_xml_tag_${path}_ok
  • ☑️ Already compliant: file_ensure_line_present_in_xml_tag_${path}_kept
  • 🟨 Repaired: file_ensure_line_present_in_xml_tag_${path}_repaired
• ❌ Error: file_ensure_line_present_in_xml_tag_${path}_error

Example

method: file_ensure_line_present_in_xml_tag
params:
  tag: VALUE
  line: VALUE
  path: VALUE

file_ensure_lines_absent

Ensure that a line is absent in a specific location.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_ensure_lines_absent_${path}_ok
  • ☑️ Already compliant: file_ensure_lines_absent_${path}_kept
  • 🟨 Repaired: file_ensure_lines_absent_${path}_repaired
• ❌ Error: file_ensure_lines_absent_${path}_error

Example

method: file_ensure_lines_absent
params:
  path: VALUE
  lines: VALUE

file_ensure_lines_present

Ensure that one or more lines are present in a file.

⚙️ Compatible targets: Linux, Windows

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_ensure_lines_present_${path}_ok
  • ☑️ Already compliant: file_ensure_lines_present_${path}_kept
  • 🟨 Repaired: file_ensure_lines_present_${path}_repaired
• ❌ Error: file_ensure_lines_present_${path}_error

Example

method: file_ensure_lines_present
params:
  path: VALUE
  lines: VALUE

file_from_http_server

Download a file if it does not exist, using curl with a fallback on wget.

⚙️ Compatible targets: Linux, Windows

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_from_http_server_${path}_ok
  • ☑️ Already compliant: file_from_http_server_${path}_kept
  • 🟨 Repaired: file_from_http_server_${path}_repaired
• ❌ Error: file_from_http_server_${path}_error

Example

method: file_from_http_server
params:
  path: VALUE
  source: VALUE

Documentation

This method finds a HTTP command-line tool and downloads the given source into the destination if it does not exist yet.

This method will NOT update the file after the first download until its removal.

On Linux based nodes it will tries curl first and fallback with wget if needed. On Windows based nodes, only curl will be used.

file_from_local_source

Ensure that a file or directory is copied from a local source.

⚙️ Compatible targets: Linux, Windows

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_from_local_source_${path}_ok
  • ☑️ Already compliant: file_from_local_source_${path}_kept
  • 🟨 Repaired: file_from_local_source_${path}_repaired
• ❌ Error: file_from_local_source_${path}_error

Example

method: file_from_local_source
params:
  path: VALUE
  source: VALUE

Documentation

Ensure that a file or directory is copied from a local source on and from the target node. The copy is not recursive if the target is a directory. To copy recursively a folder from a local source, use the File from local source recursion method.

file_from_local_source_recursion

Ensure that a file or directory is copied from a local source.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_from_local_source_${path}_ok
  • ☑️ Already compliant: file_from_local_source_${path}_kept
  • 🟨 Repaired: file_from_local_source_${path}_repaired
• ❌ Error: file_from_local_source_${path}_error

Example

method: file_from_local_source_recursion
params:
  path: VALUE
  recursion: VALUE
  source: VALUE

Documentation

Ensure that a file or directory is copied from a local source. If the source is a directory, you can force a maximum level of copy recursion.

• 0 being no recursion, which will only create an empty folder
• inf being a complete recursive copy of the folder
• 1,2,3,... will force the maximal level of recursion to copy

file_from_local_source_with_check

Ensure that a file or directory is copied from a local source if a check command succeeds.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_from_local_source_with_check_${path}_ok
  • ☑️ Already compliant: file_from_local_source_with_check_${path}_kept
  • 🟨 Repaired: file_from_local_source_with_check_${path}_repaired
• ❌ Error: file_from_local_source_with_check_${path}_error

Example

method: file_from_local_source_with_check
params:
  check_command: VALUE
  rc_ok: OPTIONAL_VALUE
  source: VALUE
  path: VALUE

Documentation

This method is a conditional file copy.

It allows comparing the source and destination, and if they are different, call a command with the source file path as argument, and only update the destination if the commands succeeds (i.e. returns a code included in rc_ok).

Examples

# To copy a configuration file only if it passes a config test:
file_from_local_source_with_check("/tmp/program.conf", "/etc/program.conf", "program --config-test", "0");

This will:

• Compare /tmp/program.conf and /etc/program.conf, and return kept if files are the same
• If not, it will execute program --config-test "/tmp/program.conf" and check the return code
• If it is one of the rc_ok codes, it will copy /tmp/program.conf into /etc/program.conf and return a repaired
• If not, it will return an error

file_from_remote_source

Ensure that a file or directory is copied from a policy server.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_from_remote_source_${path}_ok
  • ☑️ Already compliant: file_from_remote_source_${path}_kept
  • 🟨 Repaired: file_from_remote_source_${path}_repaired
• ❌ Error: file_from_remote_source_${path}_error

Example

method: file_from_remote_source
params:
  source: VALUE
  path: VALUE

Documentation

Note: This method uses the agent native file copy protocol, and can only download files from the policy server. To download a file from an external source, you can use HTTP with the file_download method.

This method requires that the policy server is configured to accept copy of the source file from the agents it will be applied to.

You can download a file from the shared files with:

/var/rudder/configuration-repository/shared-files/PATH_TO_YOUR_FILE

file_from_remote_source_recursion

Ensure that a file or directory is copied from a policy server.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_from_remote_source_${path}_ok
  • ☑️ Already compliant: file_from_remote_source_${path}_kept
  • 🟨 Repaired: file_from_remote_source_${path}_repaired
• ❌ Error: file_from_remote_source_${path}_error

Example

method: file_from_remote_source_recursion
params:
  path: VALUE
  recursion: VALUE
  source: VALUE

Documentation

This method requires that the policy server is configured to accept copy of the source file or directory from the agents it will be applied to.

You can download a file from the shared files with:

/var/rudder/configuration-repository/shared-files/PATH_TO_YOUR_DIRECTORY_OR_FILE

file_from_remote_template

Build a file from a template on the Rudder server.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${destination} with its actual canonified value.

• ✅ Ok: file_from_remote_template_${destination}_ok
  • ☑️ Already compliant: file_from_remote_template_${destination}_kept
  • 🟨 Repaired: file_from_remote_template_${destination}_repaired
• ❌ Error: file_from_remote_template_${destination}_error

Example

method: file_from_remote_template
params:
  source_template: VALUE
  destination: VALUE
  template_type: jinja2

Documentation

Write a file based on a template on the Rudder server and data available on the node

Usage

To use this method, you need to have:

• a template on the Rudder server shared folder
• data to fill this template

The template needs to be located in the shared-files folder and can be accessed with:

/var/rudder/configuration-repository/shared-files/PATH_TO_YOUR_FILE

The data that will be used while expanding the template is the data available in the agent at the time of expansion. That means:

• Agent's system variables (${sys.*}, ...) and conditions (linux, ...)
• data defined during execution (result conditions of generic methods, ...)
• conditions based on condition_ generic methods
• data defined using variable_* generic methods, which allow for example to load data from local json or yaml files.

Template types

Supported templating languages:

• mustache templates, which are documented in file_from_template_mustache
• jinja2 templates, which are documented in file_from_template_jinja2

Reporting

This method will provide extra log_warning message if the template was not updated, but the destination file is modified.

file_from_shared_folder

Ensure that a file or directory is copied from the Rudder shared folder.

⚙️ Compatible targets: Linux, Windows

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_from_shared_folder_${path}_ok
  • ☑️ Already compliant: file_from_shared_folder_${path}_kept
  • 🟨 Repaired: file_from_shared_folder_${path}_repaired
• ❌ Error: file_from_shared_folder_${path}_error

Example

method: file_from_shared_folder
params:
  source: VALUE
  hash_type: sha256
  path: VALUE

Documentation

Ensure that a file or directory is copied from the Rudder shared folder. The Rudder shared folder is located on the Rudder server under /var/rudder/configuration-repository/shared-files. Every file/folder in the shared folder will be available for every managed node. This method will download and update the destination file from a source taken from this shared folder. A file in the shared folder will be updated on the node side at agent run.

file_from_string_mustache

Build a file from a mustache string.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_from_string_mustache_${path}_ok
  • ☑️ Already compliant: file_from_string_mustache_${path}_kept
  • 🟨 Repaired: file_from_string_mustache_${path}_repaired
• ❌ Error: file_from_string_mustache_${path}_error

Example

method: file_from_string_mustache
params:
  path: VALUE
  template: VALUE

Documentation

Build a file from a mustache string. Complete mustache documentation is available in the file_from_template_mustache method documentation.

file_from_template

Build a file from a legacy CFEngine template.

⚙️ Compatible targets: Linux, Windows

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_from_template_${path}_ok
  • ☑️ Already compliant: file_from_template_${path}_kept
  • 🟨 Repaired: file_from_template_${path}_repaired
• ❌ Error: file_from_template_${path}_error

Example

method: file_from_template
params:
  source_template: VALUE
  path: VALUE

Documentation

See file_from_template_type for general documentation about templates usage.

file_from_template_jinja2

Build a file from a jinja2 template.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_from_template_${path}_ok
  • ☑️ Already compliant: file_from_template_${path}_kept
  • 🟨 Repaired: file_from_template_${path}_repaired
• ❌ Error: file_from_template_${path}_error

Example

method: file_from_template_jinja2
params:
  path: VALUE
  source_template: VALUE

Documentation

See file_from_template_type for general documentation about templates usage.

This generic method will build a file from a jinja2 template using data (conditions and variables) found in the execution context.

Setup

It requires to have the jinja2 python module installed on the node, it can usually be done in ncf with package_present("python-jinja2", "", "", "").

WARNING: If you are using a jinja2 version older than 2.7 trailing newlines will not be preserved in the destination file.

Syntax

Jinja2 is a powerful templating language, running in Python. The Jinja2 syntax reference documentation is http://jinja.pocoo.org/docs/dev/templates/ which will likely be useful, as Jinja2 is very rich and allows a lot more that what is explained here.

This section presents some simple cases that cover what can be done with mustache templating, and the way the agent data is provided to the templating engine.

The main specificity of jinja2 templating is the use of two root containers:

• classes to access currently defined conditions
• vars to access all currently defined variables

Note: You can add comments in the template, that will not be rendered in the output file with {# ... #}.

You can extend the Jinja2 templating engine by adding custom FILTERS and TESTS in the script /var/rudder/configuration-repository/ncf/10_ncf_internals/modules/extensions/jinja2_custom.py

For instance, to add a filter to uppercase a string and a test if a number is odd, you can create the file /var/rudder/configuration-repository/ncf/10_ncf_internals/modules/extensions/jinja2_custom.py on your Rudder server with the following content:

def uppercase(input):
    return input.upper()

def odd(value):
    return True if (value % 2) else False

FILTERS = {'uppercase': uppercase}
TESTS = {'odd': odd}

These filters and tests will be usable in your jinja2 templates automatically.

Conditions

To display content based on conditions definition:

{% if classes.my_condition is defined  %}
   display this if defined
{% endif %}
{% if not classes.my_condition is defined %}
   display this if not defined
{% endif %}

Note: You cannot use condition expressions here.

You can also use other tests, for example other built-in ones or those defined in jinja2_custom.py:

{% if vars.variable_prefix.my_number is odd  %}
   display if my_number is odd
{% endif %}

Scalar variables

Here is how to display a scalar variable value (integer, string, ...), if you have defined variable_string("variable_prefix", "my_variable", "my_value"):

{{ vars.variable_prefix.my_variable }}

You can also modify what is displayed by using filters. The built-in filters can be extended in jinja2_custom.py:

{{ vars.variable_prefix.my_variable | uppercase }}

Will display the variable in uppercase.

Iteration

To iterate over a list, for example defined with:

variable_iterator("variable_prefix", "iterator_name", "a,b,c", ",")

Use the following file:

{% for item in vars.variable_prefix.iterator_name %}
{{ item }} is the current iterator_name value
{% endfor %}

Which will be expanded as:

a is the current iterator_name value
b is the current iterator_name value
c is the current iterator_name value

To iterate over a container defined by the following json file, loaded with variable_dict_from_file("variable_prefix", "dict_name", "path"):

{
   "hosts": [
       "host1",
       "host2"
   ],
   "files": [
       {"name": "file1", "path": "/path1", "users": [ "user1", "user11" ] },
       {"name": "file2", "path": "/path2", "users": [ "user2" ] }
   ],
   "properties": {
       "prop1": "value1",
       "prop2": "value2"
   }
}

Use the following template:

{% for item in vars.variable_prefix.dict_name.hosts %}
{{ item }} is the current hosts value
{% endfor %}

# will display the name and path of the current file
{% for file in vars.variable_prefix.dict_name.files %}
{{ file.name }}: {{ file.path }}
{% endfor %}

# will display the users list of each file
{% for file in vars.variable_prefix.dict_name.files %}
{{ file.name }}: {{ file.users|join(' ') }}
{% endfor %}


# will display the current properties key/value pair
{% for key, value in vars.variable_prefix.dict_name.properties.items() %}
{{ key }} -> {{ value }}
{% endfor %}

Which will be expanded as:

host1 is the current hosts value
host2 is the current hosts value

# will display the name and path of the current file
file1: /path1
file2: /path2

# will display the users list of each file
file1: user1 user11
file2: user2

# will display the current properties key/value pair
prop1 -> value1
prop2 -> value2

System variables

Some sys dict variables (like sys.ipv4) are also accessible as string, for example:

• ${sys.ipv4} gives 54.32.12.4
• $[sys.ipv4[ethO]} gives 54.32.12.4
• $[sys.ipv4[eth1]} gives 10.45.3.2

These variables are not accessible as dict in the templating data, but are represented as string:

• ipv4 is a string variable in the sys dict with value 54.32.12.4
• ipv4[ethO] is a string variable in the sys dict with value 54.32.12.4
• ipv4 is not accessible as a dict in the template

To access these value, use the following syntax in your jinja2 templates:

vars.sys['ipv4[eth0]']

file_from_template_mustache

Build a file from a mustache template.

⚙️ Compatible targets: Linux, Windows

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_from_template_${path}_ok
  • ☑️ Already compliant: file_from_template_${path}_kept
  • 🟨 Repaired: file_from_template_${path}_repaired
• ❌ Error: file_from_template_${path}_error

Example

method: file_from_template_mustache
params:
  path: VALUE
  source_template: VALUE

Documentation

See file_from_template_type for general documentation about templates usage.

Syntax

Mustache is a logic-less templating language, available in a lot of languages, and used for file templating in Rudder. The mustache syntax reference is https://mustache.github.io/mustache.5.html. The Windows implementation follows the standard, the Unix one is a bit richer as describe below.

We will here describe the way to get agent data into a template. Ass explained in the general templating documentation, we can access various data in a mustache template.

The main specificity compared to standard mustache syntax of prefixes in all expanded values:

• classes to access conditions
• vars to access all variables

Classes

Here is how to display content depending on conditions definition:

{{#classes.my_condition}}
   content when my_condition is defined
{{/classes.my_condition}}

{{^classes.my_condition}}
   content when my_condition is *not* defined
{{/classes.my_condition}}

Note: You cannot use condition expressions here.

Scalar variable

Here is how to display a scalar variable value (integer, string, ...), if you have defined variable_string("variable_prefix", "my_variable", "my_value"):

{{{vars.variable_prefix.my_variable}}}

We use the triple {{{ }}} to avoid escaping html entities.

Iteration

Iteration is done using a syntax similar to scalar variables, but applied on container variables.

• Use {{#vars.container}} content {{/vars.container}} to iterate
• Use {{{.}}} for the current element value in iteration
• Use {{{key}}} for the key value in current element
• Use {{{.key}}} for the key value in current element (Linux only)
• Use {{{@}}} for the current element key in iteration (Linux only)

To iterate over a list, for example defined with:

variable_iterator("variable_prefix", "iterator_name", "a,b,c", ",")

Use the following file:

{{#vars.variable_prefix.iterator_name}}
{{{.}}} is the current iterator_name value
{{/vars.variable_prefix.iterator_name}}

Which will be expanded as:

a is the current iterator_name value
b is the current iterator_name value
c is the current iterator_name value

To iterate over a container defined by the following json file, loaded with variable_dict_from_file("variable_prefix", "dict_name", "path"):

{
   "hosts": [
       "host1",
       "host2"
   ],
   "files": [
       {"name": "file1", "path": "/path1", "users": [ "user1", "user11" ] },
       {"name": "file2", "path": "/path2", "users": [ "user2" ] }
   ],
   "properties": {
       "prop1": "value1",
       "prop2": "value2"
   }
}

Use the following template:

{{#vars.variable_prefix.dict_name.hosts}}
{{{.}}} is the current hosts value
{{/vars.variable_prefix.dict_name.hosts}}

# will display the name and path of the current file
{{#vars.variable_prefix.dict_name.files}}
{{{name}}}: {{{path}}}
{{/vars.variable_prefix.dict_name.files}}
# Lines below will only be properly rendered in unix Nodes
# will display the users list of each file
{{#vars.variable_prefix.dict_name.files}}
{{{name}}}:{{#users}} {{{.}}}{{/users}}
{{/vars.variable_prefix.dict_name.files}}


# will display the current properties key/value pair
{{#vars.variable_prefix.dict_name.properties}}
{{{@}}} -> {{{.}}}
{{/vars.variable_prefix.dict_name.properties}}

Which will be expanded as:

host1 is the current hosts value
host2 is the current hosts value

# will display the name and path of the current file
file1: /path1
file2: /path2

# Lines below will only be properly rendered in unix Nodes
# will display the users list of each file
file1: user1 user11
file2: user2

# will display the current properties key/value pair
prop1 -> value1
prop2 -> value2

Note: You can use {{#-top-}} ... {{/-top-}} to iterate over the top level container.

System variables

Some sys dict variables (like sys.ipv4) are also accessible as string, for example:

• ${sys.ipv4} gives 54.32.12.4
• $[sys.ipv4[ethO]} gives 54.32.12.4
• $[sys.ipv4[eth1]} gives 10.45.3.2

These variables are not accessible as dict in the templating data, but are represented as string:

• ipv4 is a string variable in the sys dict with value 54.32.12.4
• ipv4[ethO] is a string variable in the sys dict with value 54.32.12.4
• ipv4 is not accessible as a dict in the template

To access these value, use the following syntax in your mustache templates:

{{{vars.sys.ipv4[eth0]}}}

file_from_template_type

Build a file from a template.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_from_template_${path}_ok
  • ☑️ Already compliant: file_from_template_${path}_kept
  • 🟨 Repaired: file_from_template_${path}_repaired
• ❌ Error: file_from_template_${path}_error

Example

method: file_from_template_type
params:
  source_template: VALUE
  path: VALUE
  template_type: VALUE

Documentation

These methods write a file based on a provided template and the data available to the agent.

Usage

To use these methods (file_from_template_*), you need to have:

• a template file
• data to fill this template

The template file should be somewhere on the local file system, so if you want to use a file shared from the policy server, you need to copy it first (using file_copy_from_remote_source).

It is common to use a specific folder to store those templates after copy, for example in ${sys.workdir}/tmp/templates/.

The data that will be used while expanding the template is the data available in the agent at the time of expansion. That means:

• Agent's system variables (${sys.*}, ...) and conditions (linux, ...)
• data defined during execution (result conditions of generic methods, ...)
• conditions based on condition_ generic methods
• data defined in ncf using variable_* generic methods, which allow for example to load data from local json or yaml files.

Template types

ncf currently supports three templating languages:

• mustache templates, which are documented in file_from_template_mustache
• jinja2 templates, which are documented in file_from_template_jinja2
• CFEngine templates, which are a legacy implementation that is here for compatibility, and should not be used for new templates.

Example

Here is a complete example of templating usage:

The (basic) template file, present on the server in /PATH_TO_MY_FILE/ntp.conf.mustache (for syntax reference, see file_from_template_mustache):

{{#classes.linux}}
server {{{vars.configuration.ntp.hostname}}}
{{/classes.linux}}
{{^classes.linux}}
server hardcoded.server.example
{{/classes.linux}}

And on your local node in /tmp/ntp.json, the following json file:

{ "hostname": "my.hostname.example" }

And the following policy:

# Copy the file from the policy server
file_copy_from_remote_source("/PATH_TO_MY_FILE/ntp.conf.mustache", "${sys.workdir}/tmp/templates/ntp.conf.mustache")
# Define the `ntp` variable in the `configuration` prefix from the json file
variable_dict_from_file("configuration", "ntp", "/tmp/ntp.json")
# Expand your template
file_from_template_type("${sys.workdir}/tmp/templates/ntp.conf.mustache", "/etc/ntp.conf", "mustache")
# or
# file_from_template_mustache("${sys.workdir}/tmp/templates/ntp.conf.mustache", "/etc/ntp.conf")

The destination file will contain the expanded content, for example on a Linux node:

server my.hostname.example

file_key_value_parameter_absent_in_list

Ensure that a parameter doesn't exist in a list of parameters, on one single line, in the right hand side of a key->values line.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_key_value_parameter_absent_in_list_${path}_ok
  • ☑️ Already compliant: file_key_value_parameter_absent_in_list_${path}_kept
  • 🟨 Repaired: file_key_value_parameter_absent_in_list_${path}_repaired
• ❌ Error: file_key_value_parameter_absent_in_list_${path}_error

Example

method: file_key_value_parameter_absent_in_list
params:
  key: VALUE
  closing_char_separator: OPTIONAL_VALUE
  key_value_separator: VALUE
  path: VALUE
  parameter_regex: VALUE
  parameter_separator: VALUE
  leading_char_separator: OPTIONAL_VALUE

Documentation

Edit the file, and ensure it does not contain the defined parameter in the list of values on the right hand side of a key->values line. If the parameter is there, it will be removed. Please note that the parameter can be a regular expression. It will also remove any whitespace character between the parameter and parameter_separator Optionally, you can define leading and closing character to enclose the parameters

Example

If you have an initial file (/etc/default/grub) containing

GRUB_CMDLINE_XEN="dom0_mem=16G dom0_max_vcpus=32"

To remove parameter dom0_max_vcpus=32 in the right hand side of the line, you'll need the following policy

file_ensure_key_value_parameter_not_in_list("/etc/default/grub", "GRUB_CMDLINE", "=", "dom0_max_vcpus=32", " ", "\"", "\"");

file_key_value_parameter_present_in_list

Ensure that one parameter exists in a list of parameters, on one single line, in the right hand side of a key->values line.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_key_value_parameter_present_in_list_${path}_ok
  • ☑️ Already compliant: file_key_value_parameter_present_in_list_${path}_kept
  • 🟨 Repaired: file_key_value_parameter_present_in_list_${path}_repaired
• ❌ Error: file_key_value_parameter_present_in_list_${path}_error

Example

method: file_key_value_parameter_present_in_list
params:
  key: VALUE
  parameter: VALUE
  key_value_separator: VALUE
  leading_char_separator: OPTIONAL_VALUE
  path: VALUE
  parameter_separator: VALUE
  closing_char_separator: OPTIONAL_VALUE

Documentation

Edit the file, and ensure it contains the defined parameter in the list of values on the right hand side of a key->values line. If the parameter is not there, it will be added at the end, separated by parameter_separator. Optionally, you can define leading and closing character to enclose the parameters If the key does not exist in the file, it will be added in the file, along with the parameter

Example

If you have an initial file (/etc/default/grub) containing

GRUB_CMDLINE_XEN="dom0_mem=16G"

To add parameter dom0_max_vcpus=32 in the right hand side of the line, you'll need the following policy

file_ensure_key_value_parameter_in_list("/etc/default/grub", "GRUB_CMDLINE", "=", "dom0_max_vcpus=32", " ", "\"", "\"");

file_key_value_present

Ensure that the file contains a pair of "key separator value".

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_key_value_present_${path}_ok
  • ☑️ Already compliant: file_key_value_present_${path}_kept
  • 🟨 Repaired: file_key_value_present_${path}_repaired
• ❌ Error: file_key_value_present_${path}_error

Example

method: file_key_value_present
params:
  value: VALUE
  path: VALUE
  separator: VALUE
  key: VALUE

Documentation

Edit (or create) the file, and ensure it contains an entry key -> value with arbitrary separator between the key and its value. If the key is already present, the method will change the value associated with this key.

file_key_value_present_in_ini_section

Ensure that a key-value pair is present in a section in a specific location. The objective of this method is to handle INI-style files.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_key_value_present_in_ini_section_${path}_ok
  • ☑️ Already compliant: file_key_value_present_in_ini_section_${path}_kept
  • 🟨 Repaired: file_key_value_present_in_ini_section_${path}_repaired
• ❌ Error: file_key_value_present_in_ini_section_${path}_error

Example

method: file_key_value_present_in_ini_section
params:
  path: VALUE
  value: VALUE
  section: VALUE
  name: VALUE

file_key_value_present_option

Ensure that the file contains a pair of "key separator value", with options on the spacing around the separator.

⚙️ Compatible targets: Linux, Windows

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_key_value_present_${path}_ok
  • ☑️ Already compliant: file_key_value_present_${path}_kept
  • 🟨 Repaired: file_key_value_present_${path}_repaired
• ❌ Error: file_key_value_present_${path}_error

Example

method: file_key_value_present_option
params:
  separator: VALUE
  option: strict
  key: VALUE
  value: VALUE
  path: VALUE

Documentation

Edit (or create) the file, and ensure it contains an entry key -> value with arbitrary separator between the key and its value. If the key is already present, the method will change the value associated with this key.

file_keys_values_present

Ensure that the file contains all pairs of "key separator value", with arbitrary separator between each key and its value.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_keys_values_present_${path}_ok
  • ☑️ Already compliant: file_keys_values_present_${path}_kept
  • 🟨 Repaired: file_keys_values_present_${path}_repaired
• ❌ Error: file_keys_values_present_${path}_error

Example

method: file_keys_values_present
params:
  keys: VALUE
  path: VALUE
  separator: VALUE

Documentation

This method ensures key-value pairs are present in a file.

Usage

This method will iterate over the key-value pairs in the dict, and:

• If the key is not defined in the destination, add the key + separator + value line.
• If the key is already present in the file, replace the key + separator + anything by key + separator + value

This method always ignores spaces and tabs when replacing (which means for example that key = value will match the = separator).

Keys are considered unique (to allow replacing the value), so you should use file_ensure_lines_present if you want to have multiple lines with the same key.

Example

If you have an initial file (/etc/myfile.conf) containing:

key1 = something
key3 = value3

To define key-value pairs, use the variable_dict or variable_dict_from_file methods.

For example, if you use the following content (stored in /tmp/data.json):

{
   "key1": "value1",
   "key2": "value2"
}

With the following policy:

# Define the `content` variable in the `configuration` prefix from the json file
variable_dict_from_file("configuration", "content", "/tmp/data.json")
# Enforce the presence of the key-value pairs
file_ensure_keys_values("/etc/myfile.conf", "configuration.content", " = ")

The destination file (/etc/myfile.conf) will contain:

key1 = value1
key3 = value3
key2 = value2

file_line_present_in_ini_section

Ensure that a line is present in a section in a specific location. The objective of this method is to handle INI-style files.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_line_present_in_ini_section_${path}_ok
  • ☑️ Already compliant: file_line_present_in_ini_section_${path}_kept
  • 🟨 Repaired: file_line_present_in_ini_section_${path}_repaired
• ❌ Error: file_line_present_in_ini_section_${path}_error

Example

method: file_line_present_in_ini_section
params:
  path: VALUE
  section: VALUE
  line: VALUE

file_line_present_in_xml_tag

Ensure that a line is present in a tag in a specific location. The objective of this method is to handle XML-style files. Note that if the tag is not present in the file, it won't be added, and the edition will fail.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_line_present_in_xml_tag_${path}_ok
  • ☑️ Already compliant: file_line_present_in_xml_tag_${path}_kept
  • 🟨 Repaired: file_line_present_in_xml_tag_${path}_repaired
• ❌ Error: file_line_present_in_xml_tag_${path}_error

Example

method: file_line_present_in_xml_tag
params:
  path: VALUE
  tag: VALUE
  line: VALUE

file_lines_absent

Ensure that a line is absent in a specific location.

⚙️ Compatible targets: Linux, Windows

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_lines_absent_${path}_ok
  • ☑️ Already compliant: file_lines_absent_${path}_kept
  • 🟨 Repaired: file_lines_absent_${path}_repaired
• ❌ Error: file_lines_absent_${path}_error

Example

method: file_lines_absent
params:
  lines: VALUE
  path: VALUE

Documentation

Edit the file, and ensure it does not contain the defined line. Regular expression can be used for both the file name and the lines absent.

file_lines_present

Ensure that one or more lines are present in a file.

⚙️ Compatible targets: Linux, Windows

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_lines_present_${path}_ok
  • ☑️ Already compliant: file_lines_present_${path}_kept
  • 🟨 Repaired: file_lines_present_${path}_repaired
• ❌ Error: file_lines_present_${path}_error

Example

method: file_lines_present
params:
  lines: VALUE
  path: VALUE

Documentation

Edit the file, and ensure it contains the defined line(s). Regular expression can be used for the file name.

file_present

Create a file if it doesn't exist.

⚙️ Compatible targets: Linux, Windows

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_present_${path}_ok
  • ☑️ Already compliant: file_present_${path}_kept
  • 🟨 Repaired: file_present_${path}_repaired
• ❌ Error: file_present_${path}_error

Example

method: file_present
params:
  path: VALUE

file_remove

Remove a file if it exists.

⚙️ Compatible targets: Linux, Windows

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_remove_${path}_ok
  • ☑️ Already compliant: file_remove_${path}_kept
  • 🟨 Repaired: file_remove_${path}_repaired
• ❌ Error: file_remove_${path}_error

Example

method: file_remove
params:
  path: VALUE

file_replace_lines

Ensure that a line in a file is replaced by another one.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_replace_lines_${path}_ok
  • ☑️ Already compliant: file_replace_lines_${path}_kept
  • 🟨 Repaired: file_replace_lines_${path}_repaired
• ❌ Error: file_replace_lines_${path}_error

Example

method: file_replace_lines
params:
  path: VALUE
  replacement: VALUE
  line: VALUE

Documentation

You can replace lines in a files, based on regular expression and captured pattern

Syntax

The content to match in the file is a PCRE regular expression, unanchored that you can replace with the content of replacement.

Content can be captured in regular expression, and be reused with the notation ${match.1} (for first matched content), ${match.2} for second, etc, and the special captured group ${match.0} for the whole text.

This regular expression must not match the string used as a replacement. For example, to set kernel.shmmax=5678, the regular expression would be kernel.shmmax=(?!5678$).* and the string used as replacement kernel.shmmax=5678 Note that if you want to replace a key-value line, method File key-value present is more suited.

Example

Here is an example to remove enclosing specific tags

file_replace_lines("/PATH_TO_MY_FILE/file", "<my>(.*)<pattern>", "my ${match.1} pattern")

file_report_content

Report the content of a file.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_report_content_${path}_ok
  • ☑️ Already compliant: file_report_content_${path}_kept
  • 🟨 Repaired: file_report_content_${path}_repaired
• ❌ Error: file_report_content_${path}_error

Example

method: file_report_content
params:
  regex: OPTIONAL_VALUE
  path: VALUE
  context: OPTIONAL_VALUE

Documentation

Report the content of a file.

This method does nothing on the system, but only reports a complete or partial content from a given file. This allows centralizing this information on the server, and avoid having to connect on each node to get this information.

NOTE: This method only works in "Full Compliance" reporting mode.

Parameters

Target

This is the file you want to report content from. The method will return an error if it does not exist.

Regex

If empty, the method will report the whole file content. If set, the method will grep the file for the given regular expression, and report the result.

Context

When specifying a regex, will add the number of lines of context around matches (default is 0, i.e. no context).

When reporting the whole file, this parameter is ignored.

Examples

# To get the whole /etc/hosts content
file_report_content("/etc/hosts", "", "");
# To get lines starting by "nameserver" in /etc/resolv.conf
file_report_content("/etc/resolv.conf", "^nameserver", "");
# To get lines containing "rudder" from /etc/hosts with 3 lines of context
file_report_content("/etc/hosts", "rudder", "3");

file_report_content_head

Report the head of a file.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_report_content_head_${path}_ok
  • ☑️ Already compliant: file_report_content_head_${path}_kept
  • 🟨 Repaired: file_report_content_head_${path}_repaired
• ❌ Error: file_report_content_head_${path}_error

Example

method: file_report_content_head
params:
  path: VALUE
  limit: OPTIONAL_VALUE

Documentation

Report the head of a file.

This method does nothing on the system, but only reports a partial content from a given file. This allows centralizing this information on the server, and avoid having to connect on each node to get this information.

NOTE: This method only works in "Full Compliance" reporting mode.

Parameters

Target

This is the file you want to report content from. The method will return an error if it does not exist.

Limit

The number of line to report.

Examples

# To get the 3 first line of /etc/hosts
file_report_content("/etc/hosts", "3");

file_report_content_tail

Report the tail of a file.

⚙️ Compatible targets: Linux, Windows

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_report_content_tail_${path}_ok
  • ☑️ Already compliant: file_report_content_tail_${path}_kept
  • 🟨 Repaired: file_report_content_tail_${path}_repaired
• ❌ Error: file_report_content_tail_${path}_error

Example

method: file_report_content_tail
params:
  path: VALUE
  limit: OPTIONAL_VALUE

Documentation

Report the tail of a file.

This method does nothing on the system, but only reports a partial content from a given file. This allows centralizing this information on the server, and avoid having to connect on each node to get this information.

NOTE: This method only works in "Full Compliance" reporting mode.

Parameters

Target

This is the file you want to report content from. The method will return an error if it does not exist.

Limit

The number of line to report.

Examples

 - name: Get the first 3 lines of /etc/hosts
   method: file_report_content_tail
   params:
     path: /etc/hosts
     limit: '3'

file_symlink_present

Create a symlink at a destination path and pointing to a source target except if a file or directory already exists.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_symlink_present_${path}_ok
  • ☑️ Already compliant: file_symlink_present_${path}_kept
  • 🟨 Repaired: file_symlink_present_${path}_repaired
• ❌ Error: file_symlink_present_${path}_error

Example

method: file_symlink_present
params:
  path: VALUE
  source: VALUE

file_symlink_present_force

Create a symlink at a destination path and pointing to a source target even if a file or directory already exists.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_symlink_present_${path}_ok
  • ☑️ Already compliant: file_symlink_present_${path}_kept
  • 🟨 Repaired: file_symlink_present_${path}_repaired
• ❌ Error: file_symlink_present_${path}_error

Example

method: file_symlink_present_force
params:
  source: VALUE
  path: VALUE

file_symlink_present_option

Create a symlink at a destination path and pointing to a source target. This is also possible to enforce its creation.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_symlink_present_${path}_ok
  • ☑️ Already compliant: file_symlink_present_${path}_kept
  • 🟨 Repaired: file_symlink_present_${path}_repaired
• ❌ Error: file_symlink_present_${path}_error

Example

method: file_symlink_present_option
params:
  enforce: VALUE
  source: VALUE
  path: VALUE

file_template_expand

This is a bundle to expand a template in a specific location.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: file_template_expand_${path}_ok
  • ☑️ Already compliant: file_template_expand_${path}_kept
  • 🟨 Repaired: file_template_expand_${path}_repaired
• ❌ Error: file_template_expand_${path}_error

Example

method: file_template_expand
params:
  mode: VALUE
  owner: VALUE
  group: VALUE
  path: VALUE
  tml_file: VALUE

group_absent

Make sure a group is absent.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${name} with its actual canonified value.

• ✅ Ok: group_absent_${name}_ok
  • ☑️ Already compliant: group_absent_${name}_kept
  • 🟨 Repaired: group_absent_${name}_repaired
• ❌ Error: group_absent_${name}_error

Example

method: group_absent
params:
  name: VALUE

group_present

Create a group.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${name} with its actual canonified value.

• ✅ Ok: group_present_${name}_ok
  • ☑️ Already compliant: group_present_${name}_kept
  • 🟨 Repaired: group_present_${name}_repaired
• ❌ Error: group_present_${name}_error

Example

method: group_present
params:
  name: VALUE

http_request_check_status_headers

Checks status of an HTTP URL.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${url} with its actual canonified value.

• ✅ Ok: http_request_check_status_headers_${url}_ok
  • ☑️ Already compliant: http_request_check_status_headers_${url}_kept
  • 🟨 Repaired: http_request_check_status_headers_${url}_repaired
• ❌ Error: http_request_check_status_headers_${url}_error

Example

method: http_request_check_status_headers
params:
  url: VALUE
  expected_status: VALUE
  headers: OPTIONAL_VALUE
  method: VALUE

Documentation

Perform a HTTP request on the URL, method and headers provided and check that the response has the expected status code (ie 200, 404, 503, etc)

http_request_content_headers

Make an HTTP request with a specific header.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${url} with its actual canonified value.

• ✅ Ok: http_request_content_headers_${url}_ok
  • ☑️ Already compliant: http_request_content_headers_${url}_kept
  • 🟨 Repaired: http_request_content_headers_${url}_repaired
• ❌ Error: http_request_content_headers_${url}_error

Example

method: http_request_content_headers
params:
  content: VALUE
  url: VALUE
  headers: OPTIONAL_VALUE
  method: VALUE

Documentation

Perform a HTTP request on the URL, method and headers provided and send the content provided. Will return an error if the request failed.

kernel_module_configuration

Ensure that the modprobe configuration of a given kernel module is correct.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${name} with its actual canonified value.

• ✅ Ok: kernel_module_configuration_${name}_ok
  • ☑️ Already compliant: kernel_module_configuration_${name}_kept
  • 🟨 Repaired: kernel_module_configuration_${name}_repaired
• ❌ Error: kernel_module_configuration_${name}_error

Example

method: kernel_module_configuration
params:
  configuration: VALUE
  name: VALUE

Documentation

Ensure that the modprobe configuration of a given kernel module is correct. Rudder will search for the module configuration in a per-module dedicated section in /etc/modprobe.d/managed_by_rudder.conf.

• If the module configuration is not found or incorrect, Rudder will (re-)create its configuration.
• If the module is configured but with a different option file than used by Rudder, it will add the expected one in /etc/modprobe.d/managed_by_rudder.conf but will leave intact the already present one.

The configuration syntax must respect the one used by /etc/modprobe.d defined in the modprobe.d manual page.

  # To pass a parameter to a module:
  options module_name parameter_name=parameter_value
  # To blacklist a module
  blacklist modulename
  # etc...

Notes:

If you want to force the module to be loaded at boot, use instead the method kernel_module_enabled_at_boot which uses other Rudder dedicated files.

Example:

To pass options to a broadcom module

• name = b43
• configuration = options b43 nohwcrypt=1 qos=0

Will produce the resulting block in /etc/modprobe.d/managed_by_rudder.conf:

### b43 start section
options b43 nohwcrypt=1 qos=0
### b43 end section

kernel_module_enabled_at_boot

Ensure that a given kernel module will be loaded at system boot.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${name} with its actual canonified value.

• ✅ Ok: kernel_module_enabled_at_boot_${name}_ok
  • ☑️ Already compliant: kernel_module_enabled_at_boot_${name}_kept
  • 🟨 Repaired: kernel_module_enabled_at_boot_${name}_repaired
• ❌ Error: kernel_module_enabled_at_boot_${name}_error

Example

method: kernel_module_enabled_at_boot
params:
  name: VALUE

Documentation

Ensure that a given kernel module is enabled at boot on the system. This method only works on systemd systems. Rudder will look for a line matching the module name in a given section in the file:

• /etc/modules-load.d/enabled_by_rudder.conf on systemd systems

If the module is already enabled by a different option file than used by Rudder, it will add an entry in the file managed by Rudder listed above, and leave intact the already present one. The modifications are persistent and made line per line, meaning that this Generic Method will never remove lines in the configuration file but only add it if needed.

Please note that this method will not load the module nor configure it, it will only enable its loading at system boot. If you want to force the module to be loaded, use instead the method kernel_module_loaded. If you want to configure the module, use instead the method kernel_module_configuration.

kernel_module_loaded

Ensure that a given kernel module is loaded on the system.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${name} with its actual canonified value.

• ✅ Ok: kernel_module_loaded_${name}_ok
  • ☑️ Already compliant: kernel_module_loaded_${name}_kept
  • 🟨 Repaired: kernel_module_loaded_${name}_repaired
• ❌ Error: kernel_module_loaded_${name}_error

Example

method: kernel_module_loaded
params:
  name: VALUE

Documentation

Ensure that a given kernel module is loaded on the system. If the module is not loaded, it will try to load it via modprobe.

kernel_module_not_loaded

Ensure that a given kernel module is not loaded on the system.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${name} with its actual canonified value.

• ✅ Ok: kernel_module_not_loaded_${name}_ok
  • ☑️ Already compliant: kernel_module_not_loaded_${name}_kept
  • 🟨 Repaired: kernel_module_not_loaded_${name}_repaired
• ❌ Error: kernel_module_not_loaded_${name}_error

Example

method: kernel_module_not_loaded
params:
  name: VALUE

Documentation

Ensure that a given kernel module is not loaded on the system. If the module is loaded, it will try to unload it using modprobe.

monitoring_parameter

Add a monitoring parameter to a node (requires a monitoring plugin).

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${key} with its actual canonified value.

• ✅ Ok: monitoring_parameter_${key}_ok
  • ☑️ Already compliant: monitoring_parameter_${key}_kept
  • 🟨 Repaired: monitoring_parameter_${key}_repaired
• ❌ Error: monitoring_parameter_${key}_error

Example

method: monitoring_parameter
params:
  value: VALUE
  key: VALUE

Documentation

This method adds monitoring parameters to rudder nodes. The monitoring parameters are used to pass configuration to the monitoring plugins running with Rudder. Expected keys and parameters are specific to each plugin and can be found in their respective documentation.

monitoring_template

Add a monitoring template to a node (requires a monitoring plugin).

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${template} with its actual canonified value.

• ✅ Ok: monitoring_template_${template}_ok
  • ☑️ Already compliant: monitoring_template_${template}_kept
  • 🟨 Repaired: monitoring_template_${template}_repaired
• ❌ Error: monitoring_template_${template}_error

Example

method: monitoring_template
params:
  template: VALUE

Documentation

This method assigns monitoring templates to a Rudder node. The Rudder plugin respective to each monitoring platform will apply those templates to the node.

package_absent

Enforce the absence of a package.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${name} with its actual canonified value.

• ✅ Ok: package_absent_${name}_ok
  • ☑️ Already compliant: package_absent_${name}_kept
  • 🟨 Repaired: package_absent_${name}_repaired
• ❌ Error: package_absent_${name}_error

Example

method: package_absent
params:
  provider: default
  name: VALUE
  version: OPTIONAL_VALUE
  architecture: OPTIONAL_VALUE

Documentation

See package_state for documentation.

package_check_installed

Verify if a package is installed in any version.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${name} with its actual canonified value.

• ✅ Ok: package_check_installed_${name}_ok
  • ☑️ Already compliant: package_check_installed_${name}_kept
  • 🟨 Repaired: package_check_installed_${name}_repaired
• ❌ Error: package_check_installed_${name}_error

Example

method: package_check_installed
params:
  name: VALUE

Documentation

This bundle will define a condition package_check_installed_${file_name}_{ok, reached, kept} if the package is installed, or package_check_installed_${file_name}_{not_ok, reached, not_kept, failed} if the package is not installed

package_install

Install or update a package in its latest version available.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${name} with its actual canonified value.

• ✅ Ok: package_install_${name}_ok
  • ☑️ Already compliant: package_install_${name}_kept
  • 🟨 Repaired: package_install_${name}_repaired
• ❌ Error: package_install_${name}_error

Example

method: package_install
params:
  name: VALUE

package_install_version

Install or update a package in a specific version.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${name} with its actual canonified value.

• ✅ Ok: package_install_${name}_ok
  • ☑️ Already compliant: package_install_${name}_kept
  • 🟨 Repaired: package_install_${name}_repaired
• ❌ Error: package_install_${name}_error

Example

method: package_install_version
params:
  name: VALUE
  package_version: VALUE

package_install_version_cmp

Install a package or verify if it is installed in a specific version, or higher or lower version than a version specified.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${name} with its actual canonified value.

• ✅ Ok: package_install_${name}_ok
  • ☑️ Already compliant: package_install_${name}_kept
  • 🟨 Repaired: package_install_${name}_repaired
• ❌ Error: package_install_${name}_error

Example

method: package_install_version_cmp
params:
  version_comparator: ==
  name: VALUE
  action: VALUE
  package_version: VALUE

Documentation

Example:

methods:
    "any" usebundle => package_install_version_cmp("postgresql", ">=", "9.1", "verify");

package_install_version_cmp_update

Install a package or verify if it is installed in a specific version, or higher or lower version than a version specified, optionally test update or not (Debian-, Red Hat- or SUSE-like systems only).

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${name} with its actual canonified value.

• ✅ Ok: package_install_${name}_ok
  • ☑️ Already compliant: package_install_${name}_kept
  • 🟨 Repaired: package_install_${name}_repaired
• ❌ Error: package_install_${name}_error

Example

method: package_install_version_cmp_update
params:
  update_policy: VALUE
  name: VALUE
  version_comparator: ==
  package_version: VALUE
  action: VALUE

Documentation

Example:

methods:
    "any" usebundle => package_install_version_cmp_update("postgresql", ">=", "9.1", "verify", "false");

package_present

Enforce the presence of a package.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${name} with its actual canonified value.

• ✅ Ok: package_present_${name}_ok
  • ☑️ Already compliant: package_present_${name}_kept
  • 🟨 Repaired: package_present_${name}_repaired
• ❌ Error: package_present_${name}_error

Example

method: package_present
params:
  name: VALUE
  provider: default
  architecture: OPTIONAL_VALUE
  version: OPTIONAL_VALUE

Documentation

See package_state for documentation.

package_remove

Remove a package.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${name} with its actual canonified value.

• ✅ Ok: package_remove_${name}_ok
  • ☑️ Already compliant: package_remove_${name}_kept
  • 🟨 Repaired: package_remove_${name}_repaired
• ❌ Error: package_remove_${name}_error

Example

method: package_remove
params:
  name: VALUE

Documentation

Example:

methods:
    "any" usebundle => package_remove("htop");

package_state

Enforce the state of a package.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${name} with its actual canonified value.

• ✅ Ok: package_state_${name}_ok
  • ☑️ Already compliant: package_state_${name}_kept
  • 🟨 Repaired: package_state_${name}_repaired
• ❌ Error: package_state_${name}_error

Example

method: package_state
params:
  provider: default
  version: OPTIONAL_VALUE
  name: VALUE
  architecture: OPTIONAL_VALUE
  state: present

Documentation

These methods manage packages using a package manager on the system.

package_present and package_absent use a new package implementation, different from package_install_*, package_remove_* and package_verify_*. It should be more reliable, and handle upgrades better. It is compatible though, and you can call generic methods from both implementations on the same host. The only drawback is that the agent will have to maintain double caches for package lists, which may cause a little unneeded overhead. These methods will update the corresponding package if updates are available New updates may not be detected even if there are some available, this is due to the update cache that is refresh every 4 hours by default, you can modify this behaviour called updates_cache_expire in rudder global parameter

Package parameters

There is only one mandatory parameter, which is the package name to install. When it should be installed from a local package, you need to specify the full path to the package as name.

The version parameter allows specifying a version you want installed (not supported with snap). It should be the complete versions string as used by the used package manager. This parameter allows two special values:

• any which is the default value, and is satisfied by any version of the given package
• latest which will ensure, at each run, that the package is at the latest available version.

The last parameter is the provider, which is documented in the next section.

You can use package_state_options to pass options to the underlying package manager (currently only with apt package manager).

Note: On RPM-based systems, to get the precise version to use in the version parameter, you can use the following commands:

sudo rpm --qf "%|EPOCH?{%{epoch}:}:{}|%{version}-%{release}\n" -q PACKAGE_NAME

# Examples
sudo rpm --qf "%|EPOCH?{%{epoch}:}:{}|%{version}-%{release}\n" -q htop
# also works with different versions expressions
sudo rpm --qf "%|EPOCH?{%{epoch}:}:{}|%{version}-%{release}\n" -q htop-3.3.0
sudo rpm --qf "%|EPOCH?{%{epoch}:}:{}|%{version}-%{release}\n" -q htop-3.3.0-1.fc39

Package providers

This method supports several package managers. You can specify the package manager you want to use or let the method choose the default for the local system.

The package providers include a caching system for package information. The package lists (installed, available and available updates) are only updated when the cache expires, or when an operation is made by the agent on packages.

Note: The implementation of package operations is done in scripts called modules, which you can find in ${sys.workdir}/modules/packages/.

apt

This package provider uses apt/dpkg to manage packages on the system. dpkg will be used for all local actions, and apt is only needed to manage update and installation from a repository.

rpm

This package provider uses yum/rpm to manage packages on the system. rpm will be used for all local actions, and yum is only needed to manage update and installation from a repository.

It is able to downgrade packages when specifying an older version.

zypper

This package provider uses zypper/rpm to manage packages on the system. rpm will be used for all local actions, and zypper is only needed to manage update and installation from a repository.

Note: If the package version you want to install contains an epoch, you have to specify it in the version in the epoch:version form, like reported by zypper info.

zypper_pattern

This package provider uses zypper with the -t pattern option to manage zypper patterns or meta-packages on the system.

Since a zypper pattern can be named differently than the rpm package name providing it, please always use the exact pattern name (as listed in the output of zypper patterns) when using this provider.

Note: When installing a pattern from a local rpm file, Rudder assumes that the pattern is built following the official zypper documentation.

Older implementations of zypper patterns may not be supported by this module.

This provider doesn't support installation from a file.

slackpkg

This package provider uses Slackware's installpkg and upgradepkg tools to manage packages on the system

pkg

This package provider uses FreeBSD's pkg to manage packages on the system. This provider doesn't support installation from a file.

ips

This package provider uses Solaris's pkg command to manage packages from IPS repositories on the system. This provider doesn't support installation from a file.

nimclient

This package provider uses AIX's nim client to manage packages from nim This provider doesn't support installation from a file.

snap

This package provider uses Ubuntu's snap to manage packages on the system This provider doesn't support installation from a file.

Examples

# To install postgresql in version 9.1 for x86_64 architecture
package_present("postgresql", "9.1", "x86_64", "");
# To ensure postgresql is always in the latest available version
package_present("postgresql", "latest", "", "");
# To ensure installing postgresql in any version
package_present("postgresql", "", "", "");
# To ensure installing postgresql in any version, forcing the yum provider
package_present("postgresql", "", "", "yum");
# To ensure installing postgresql from a local package
package_present("/tmp/postgresql-9.1-1.x86_64.rpm", "", "", "");
# To remove postgresql
package_absent("postgresql", "", "", "");

See also : package_present, package_absent, package_state_options

package_state_options

Enforce the state of a package with options.

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${name} with its actual canonified value.

• ✅ Ok: package_state_options_${name}_ok
  • ☑️ Already compliant: package_state_options_${name}_kept
  • 🟨 Repaired: package_state_options_${name}_repaired
• ❌ Error: package_state_options_${name}_error

Example

method: package_state_options
params:
  options: OPTIONAL_VALUE
  state: present
  architecture: OPTIONAL_VALUE
  provider: default
  name: VALUE
  version: OPTIONAL_VALUE

Documentation

See package_state for documentation.

package_state_windows

This method manage packages using a chocolatey on the system.

⚙️ Compatible targets: Windows

Parameters

Outcome conditions

You need to replace ${PackageName} with its actual canonified value.

• ✅ Ok: package_state_windows_${PackageName}_ok
  • ☑️ Already compliant: package_state_windows_${PackageName}_kept
  • 🟨 Repaired: package_state_windows_${PackageName}_repaired
• ❌ Error: package_state_windows_${PackageName}_error

Example

method: package_state_windows
params:
  Provider: choco
  Status: present
  PackageName: VALUE
  ProviderParams: OPTIONAL_VALUE
  Version: OPTIONAL_VALUE
  Source: OPTIONAL_VALUE
  AutoUpgrade: 'true'
  Params: OPTIONAL_VALUE

Documentation

Install a windows package using a given provider

Parameters

Required args:

• PackageName Name of target package
• Status can be "present" or "absent"

Optional args:

• Provider Provider used to installed the package
• Params Package parameters, passed to the installer
• Version can be "any", "latest" or any exact specific version number
• Source "any" or any specific arch
• ProviderParams provider specific options
• AutoUpgrade default set to false

Providers

choco

The method is a simple transcription of the cchoco cChocoPaclageInstaller DSC resource, adapted to Rudder. The DSC module cchoco must be installed on your node before trying to use this method.

You can check the cchoco/chocolatey documentation to get more detailed information on the parameters. WARNING: If some exceptions are thrown about undefined env PATH variable after fresh cchoco lib in rudder, you may need to reboot your machine or notify your system that the env variables have been changed.

package_verify

Verify if a package is installed in its latest version available.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${name} with its actual canonified value.

• ✅ Ok: package_install_${name}_ok
  • ☑️ Already compliant: package_install_${name}_kept
  • 🟨 Repaired: package_install_${name}_repaired
• ❌ Error: package_install_${name}_error

Example

method: package_verify
params:
  name: VALUE

package_verify_version

Verify if a package is installed in a specific version.

⚙️ Compatible targets: Linux

⚠️ Deprecated: This method is deprecated and should not be used.

Parameters

Outcome conditions

You need to replace ${name} with its actual canonified value.

• ✅ Ok: package_install_${name}_ok
  • ☑️ Already compliant: package_install_${name}_kept
  • 🟨 Repaired: package_install_${name}_repaired
• ❌ Error: package_install_${name}_error

Example

method: package_verify_version
params:
  version: VALUE
  name: VALUE

permissions

Set permissions on a file or directory (non recursively).

⚙️ Compatible targets: Linux

Parameters

Outcome conditions

You need to replace ${path} with its actual canonified value.

• ✅ Ok: permissions_${path}_ok
  • ☑️ Already compliant: permissions_${path}_kept
  • 🟨 Repaired: permissions_${path}_repaired
• ❌ Error: permissions_${path}_error