Rudder 4.3 - User ManualReference

techniques
+--- category.xml
+--- fileConfiguration
|   +--- category.xml
|   +--- security
|   |   +--- filesPermissions
|   |   |   +--- 1.0
|   |   |   |   +--- permlist.st
|   |   |   |   +--- metadata.xml
|   |   |   |   +--- filesPermissions.st
|   |   +--- category.xml
|   |   +--- sudoCheck
|   |   |   +--- 2.0
|   |   |   |   +--- metadata.xml
|   |   |   |   +--- sudoCheck.st
|   |   |   +--- 1.0
|   |   |   |   +--- metadata.xml
|   |   |   |   +--- sudoCheck.st

These files must reside in a folder with a version number. For each Technique, there can be several versions, Rudder will let you choose the version when creating a Directive.

The version number follows a formating "a la Debian" as described here: https://www.debian.org/doc/debian-policy/index.html#s-f-version, (without the debian_revision version)

<TECHNIQUE id="technique_unique_id" name="human_name_of_the_technique">
  <DESCRIPTION>Description of the Technique</DESCRIPTION>
  <LONG_DESCRIPTION>Long description of the technique</LONG_DESCRIPTION>
  <DEPRECATED>Deprecation message</DEPRECATED>                <!-- Mark the Technique as deprecated, deprecation message is mandatory, Only available since Rudder 3.0 -->
  <DISPLAY>true/false</DISPLAY>                               <!-- Define if the Technique is displayed in the interface or not. Default value : true -->
  <COMPATIBLE>                                                <!-- Optional, describe the version of the OS and Agent the Technique has been tested on. Only for information purpose -->
    <OS version=">=2.5">OS Name</OS>                          <!-- Optional; OS Name and version on which the Technique has been tested -->
    <AGENT version=">=3.6">cfengine-community</AGENT>         <!-- Optional; Agent name and version on which the Technique has been tested -->
  </COMPATIBLE>
  <MULTIINSTANCE>true/false</MULTIINSTANCE>                   <!-- Optional; defines if several instances of this template with differents variables can be deployed on a node; default value: false -->
  <POLICYGENERATION>separated</POLICYGENERATION>              <!-- Optional; defines if each Directives based on this Technique will be in a separated folder; default value: false. Note, if this parameter is set, you'll have to use the RudderUniqueID special placeholder to avoid duplicate names for methods and bundles -->

  <SYSTEM>true/false</SYSTEM>                                 <!-- Optional, defines if this Technique is a system Technique (internal Rudder usage); default value: false -->
  <BUNDLES>                                                   <!-- List of the bundles that must be included in the bundlesequence -->
    <NAME>BundleName</NAME>
  </BUNDLES>
  <TMLS>                                                      <!-- List of all the templates defined by this Technique -->
   <TML name="tmlName">                                       <!-- Container for a TML (without the trailing .st -->
    <OUTPATH>relativ/path/of/file</OUTPATH>                   <!-- Optional; defines the relative path for the generated file for this template; default: techniqueName/version/tmlName.cf -->
    <INCLUDED>true/false</INCLUDED>                           <!-- Optional; defines if the template must be in the inputs list of the generated promises; default: true -->
   </TML>
  </TMLS>
  <FILES>                                                     <!-- List of files to be copied "as-is" with this Technique. StringTemplate parser is NOT used on these. -->
    <FILE name="file.txt">                                    <!-- Container for a FILE. name (mandatory) = path to the file to copy, can be relative or absolute from RUDDER_CONFIGURATION_REPOSITORY/ (see below) -->
    <FILE name="file2.txt"><OUTPATH>technique_name/newname.txt</OUTPATH></FILE>
    <FILE name="RUDDER_CONFIGURATION_REPOSITORY/directory/other/file.txt"><OUTPATH>technique_name/filename</OUTPATH></FILE>
  </FILES>
  <TRACKINGVARIABLE>                                          <!-- Defines a special system variable TRACKINGKEY that contains all the necessary information to track which Directive generated the promises -->
    <SAMESIZEAS>VariableName</SAMESIZEAS>                     <!-- Optional; defines the cardinality of this variable based on the cardinality of the VariableName -->
  </TRACKINGVARIABLE>

  <RUNHOOKS>                                                  <!-- Optionnal; defines the list of pre and post hooks for techniques with separated policy generation mode -->
    <PRE bundle="pre_hook_bundle">                            <!-- Optionnal; name of the bundle/method to run before any directive based on this technique is run -->
      <REPORT name="Component name"/>                         <!-- Component Name for the report of the hook
      <PARAMETER name="name" value="value"/>                  <!-- Optionnal; parameter to pass to the hook
    </PRE>
    <POST bundle="post_hook_bundle">                          <!-- Optionnal; name of the bundle/method to run after all the directives based on this technique are run -->
      <REPORT name="Component name"/>                         <!-- Component Name for the report of the hook
      <PARAMETER name="name" value="value"/>                  <!-- Optionnal; parameter to pass to the hook
    </POST>
  </RUNHOOKS>


  <SECTIONS>                                                  <!-- Lists all the sections of the promises -->
    <SECTION name="sectionName">                              <!-- Container of a section (see below) -->
    </SECTION>
  </SECTIONS>

</TECHNIQUE>

In a metadata.xml, there can be only one SECTIONS tag, that encloses one or several SECTION tags. A SECTION tag contains variables declaration and subsections. A SECTION can contains Variables definitions and SECTION.

<SECTION name="sectionName" multivalued="true/false" component="true/false" componentKey="variableName/None">

A SECTION has the following attributes:

There are three tags to create a variable:

<SELECT1/SELECT/INPUT>                                                        <!-- Depend on the display and behaviour needed -->
  <NAME>variableName</NAME>
  <DESCRIPTION>variableDescription</DESCRIPTION>
  <LONGDESCRIPTION>longDescription</LONGDESCRIPTION>                          <!-- Optional, set the text in the tooltips -->
  <UNIQUEVARIABLE>true/false</UNIQUEVARIABLE>                                 <!-- Optional, default false; if true, this variable will have the same value over all the instance of this template for a given node -->
  <ITEM>                                                                      <!-- Only for SELECT and SELECT1, list of selectable values -->
    <VALUE>value</VALUE>                                                      <!-- value that will be put in the template-->
    <LABEL>humanReadableText</LABEL>                                          <!-- value displayed in the web interface -->
  </ITEM>
  <CONSTRAINT>                                                                <!-- Optional, defines some constraints on values -->
    <DEFAULT>defaultValue</DEFAULT>                                           <!-- Optional; Defines a default value -->
    <TYPE>variableType</TYPE>                                                 <!-- Optional; default string; variable type -->
    <MAYBEEMPTY>true/false</MAYBEEMPTY>                                       <!-- Optional; default false; defines if the variable is optional or not; only for the INPUT variable -->
    <REGEX error="errorMsg">regex</REGEX>                                     <!-- Optional; only for the INPUT variable; efine a regular expression the variable should match, and an optional error message -->
    <PASSWORDHASH>hashtype</PASSWORDHASH>                                     <!-- Optional; only for the password TYPE variable; define the way a password will be handled (hashed or not, hash types allowed ...) -->
  </CONSTRAINT>
</SELECT1/SELECT/INPUT>

Note: It is possible to inline LABEL and VALUE in the ITEM tag

<ITEM label="Red" value="red"/>

is equivalent to

<ITEM>
 <LABEL>Red</LABEL>
 <VALUE>red</VALUE>
</ITEM>

Example:

<FILES>
<FILE name="file.txt"><OUTPATH>foo/bar/other-name.txt</OUTPATH></FILE>
<FILE name="RUDDER_CONFIGURATION_REPOSITORY/some/absolute/file.txt"><OUTPATH>foo/bar/some-name.txt</OUTPATH></FILE>
</FILES>

In the "NFS Client settings" Technique, there is a multivalued section with several entries. Here is a partial extract from it, with

 <SECTION name="NFS mountpoint" multivalued="true" component="true" componentKey="NFS_CLIENT_LOCAL_PATH">
     <SELECT1>
       <NAME>NFS_CLIENT_UMOUNT</NAME>
       <DESCRIPTION>Which operation should be done on this mountpoint</DESCRIPTION>
       <ITEM>
         <LABEL>Mount</LABEL>
         <VALUE>no</VALUE>
       </ITEM>
       <ITEM>
         <LABEL>Unmount</LABEL>
         <VALUE>yes</VALUE>
       </ITEM>
       <CONSTRAINT>
         <DEFAULT>no</DEFAULT>
       </CONSTRAINT>
     </SELECT1>
     <INPUT>
       <NAME>NFS_CLIENT_LOCAL_PATH</NAME>
       <DESCRIPTION>Local path to mount the remote on</DESCRIPTION>
     </INPUT>
  ...
 </SECTION>

This variable can have only one value, over all the instances of this Technique, on a node

  <SECTIONS>
      <INPUT>
        <NAME>UNIQUE</NAME>
        <DESCRIPTION>Unique variable</DESCRIPTION>
        <CONSTRAINT>
          <TYPE>string</TYPE>
        <CONSTRAINT>
        <UNIQUEVARIABLE>true</UNIQUEVARIABLE>
    </INPUT>
  </SECTIONS>

The password type allows to show an input text field whose content will be hashed when the form is submitted so that the password is never store in clear text.

Available hash formats

For now, the password field support these hash algorithms :

Technique metatdata content

To configure a password, you must specify two things in the <CONSTRAINT> section of the field:

Password field definition example

<SECTION name="Password" component="true" componentKey="USERGROUP_USER_LOGIN">
    <INPUT>
        <NAME>USERGROUP_USER_PASSWORD</NAME>
        <DESCRIPTION>Password for this account</DESCRIPTION>
        <CONSTRAINT>
            <MAYBEEMPTY>true</MAYBEEMPTY>
            <TYPE>password</TYPE>
            <PASSWORDHASH>linux-shadow-md5,linux-shadow-sha256,linux-shadow-sha512</PASSWORDHASH>
        </CONSTRAINT>
    </INPUT>
</SECTION>

Here is an extract from Technique to exhibit the use of the placeholder

bundle agent sudo_parameter_edit_sudoers_RudderUniqueID(filename, entity, nopasswd, alldo, command)
{
  vars:

      "index" slist => getindices("${entity}");

    pass1::

      "command_all[${index}]" string => "ALL=(ALL) NOPASSWD:ALL",
                      ifvarclass => "(sudo_${index}_RudderUniqueID_alldo.sudo_${index}_nopasswd).(sudo_${index}_RudderUniqueID_command_notempty|sudo_${index}_RudderUniqueID_alldo)";

It is used here in the bundle name, to ensure its unicity, and it is also used in the class name.

Some Techniques require actions to be performed only once, before and/or after all operation (for instance, ensuring that a package is installed before configuring this package). A pre and post hook mechanism has been introduced, for these uses. By convention, all pre and post hooks are located in the hooks.st file, in the System Technique common (so outside of the Technique we consider, to enforce that only one version of the hook may live in the Technique repository at a time).

Hooks have only one parameter, which is a JSON entry, in the format

{
  "parameters":
    {
       "parameterName1":"parameterValue1",
       "parameterName2":"parameterValue2",
    },
  "reports":
    [
      {"id":"DirectiveId1","mode":"enforce/audit", "technique":"techniqueName", "name":"componentName", "value":"componentValue1"},
      {"id":"DirectiveId2","mode":"enforce/audit", "technique":"techniqueName", "name":"componentName", "value":"componentValue2"},
      {"id":"DirectiveId3","mode":"enforce/audit", "technique":"techniqueName", "name":"componentName", "value":"componentValue3"},
   ]
}

The entries parameterName and parameterValue are defined by the PARAMETER tag of the section RUNHOOKS of metadata.xml, while the componentName is defined by its REPORT tag.

It is not possible, due to limitation in the format in which the variable’s values are stored in the LDAP tree, to put multivalued sections within multivalued sections.

For the moment, there is only one TRACKINGKEY, so it is not possible to have several multivalued sections that have keys.

It is a side effect of the previous limitation.