Advanced configuration management

The button Update policies on the top right of the screen, in the Status menu, allows you to force the regeneration of the policies. As changes in the inventory of the nodes are not automatically taken into account by Rudder, this feature can be useful after some changes impacting the inventory information.

The button Regenerate all policies on the top right of the screen, in the Status menu, allows you to force the regeneration of all policies. It will clear all internal caches, and force a complete computation of the policies. This is generally useful to make sure everything is correct after a problem on the central server.

Policy generation is a complex process and it is central to Rudder use. You will often want to know more about a policy generation result: what was the reason for a failure? What nodes where upated? Or even more specifics info like: where are info and debug log?

As explained in http://www.ncf.io/, ncf uses a structured directory tree composed of several layers of logic, from internal libraries to Techniques and user services. All the files and logic in these folders will be named "library" for simplicity

ncf directory structure exists in two root folders:

To share those folders to all nodes, Rudder makes a copy of these folders in two places:

Files in /var/rudder/ncf are synchronized automatically by the "rudder agent update" command when the agent runs on the server. So any modification done in files in these directories will be lost at the next synchronization.

Files under /var/rudder/share/ are updated during policy generation.

A node updates its ncf local library by copying the content of these two folders during its policy update phase.

Here we will explain how the Technique Editor integration to Rudder is done to transform ncf techniques into full fledged Rudder one. We will also get the big picture of the web flow and the resulting events triggered on Rudder server side.

Each action in the Technique Editor interface produces requests to an API defined over ncf.

All of the requests are authenticated thanks to a token passed in the JSESSIONID header. The token is generated when an authenticated user is connected to the Rudder interface (typically thanks to his browser).

That token is shared to the Technique Editor interface, which itself passes the JSESSIONID header to all requests.

If you have authentication issue, check that your Rudder session is not expired.

https://your.rudder.server/ncf-builder/#!?path=/var/rudder/configuration-repository/ncf

Get requests are triggered when accessing Technique editor.

The ncf API will parse all files in the parameter path by running "cf-promises -pjson" on all Techniques, checking that all Techniques are correctly formed.

The ncf API will also look to all Generic Methods description data to build the catalog of available Generic Methods.

The resulting information are sent back to the Technique Editor for displaying.

They are triggered when clicking on save/delete button.

The main difference with get requests is that hooks are launched before and after the action is made.

We will see all hooks behavior in the following dedicated hooks section.

On each POST request, pre- and post- hooks are executed by the Technique Editor. These hooks are used for the Rudder integration to help transform pure ncf Techniques into Rudder one.

As of March 2015, we have two post-hooks defined and no pre-hooks:

If you want to run post hooks by hand, you can use the following command:

Hooks are organized in subdirectories. The root of the sub-directories is /opt/rudder/etc/hooks.d/

Each sub-directory has a name related to the event that will trigger the hooks execution. By default, a hook directory contains a template example and a Readme.txt file explaining the generalities about hooks and the specificities of that hook (parameters, etc).

Hooks must be executable. All executable files will be used as hooks EXCEPT if they end with one of the extensions listed in /opt/rudder/etc/rudder-web.properties for property *rudder.hooks.ignore-suffixes. A common convention is to use the .disabled suffixe to do so.

Non executable files will be ignored (which allows to put other files in these directories, like a readme, for example).

Hooks parameter are passed by environment variable. Rudder will fill dedicated environment variable for each hook.

Hooks are executed sequentially, in lexical order. We encourage you to use the patter "NN-hookname", with NN a number like "05", "20", etc.

Hooks have normalized returned code. Return codes on hooks are interpreted as follow:

Hooks have a maximum execution time allowed. After some time (2s for policy generation node specific events, 30s for other cases) a warning will be issued. After a longer time (20s for policy generation node specific events, 5 min for other cases), the hook will be killed. You can change these timeouts with the following directives, that must be in the 1000 first characters of your hook script, prefixed by any type of comments characters (only the end of line is considered):

Where length is an integer, and unit is one of micro(s), ms, millisecond(s), s, second(s), m, minute(s), h, hour(s).

Available Hooked events: for now, all hooks are related to different steps of the policy generation process or node lifecycle and inventory reception. In the future, more cases will be supported.