diff --git a/src/reference/modules/usage/pages/advanced_configuration_management.adoc b/src/reference/modules/usage/pages/advanced_configuration_management.adoc index 3ea1b60b..a40202de 100644 --- a/src/reference/modules/usage/pages/advanced_configuration_management.adoc +++ b/src/reference/modules/usage/pages/advanced_configuration_management.adoc @@ -105,121 +105,6 @@ Much more information can be logged about policy generation (hook execution and updated nodes, files written, etc). All corresponding logs and verbosity levels are documented and controlled in `/opt/rudder/etc/logback.xml`. -== Understanding how Technique Editor works - -In this chapter, we are giving an overview about how the Technique Editor works and how it is -integrated with the main Rudder application. - -=== Directory layout - -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: - -* `/usr/share/ncf/tree` -** This is the standard library installation folder. It is created and updated by - the ncf package. This folder will be completely overwritten when you update ncf - package, so you should never modify anything here: it will be lost at some point. - -* `/var/rudder/configuration-repository/ncf` -** This is where you add your own ncf Generic Methods and Techniques. - Techniques created with the Technique Editor will be located here, and both - Generic and Techniques in that place will be accessible in the Technique Editor - alongside what is provided by the standard library. - -=== Sharing ncf code with nodes - -To share those folders to all nodes, Rudder makes a copy of these folders in two -places: - -* `/var/rudder/ncf`, for part common to all nodes - so NOT techniques, - ** `/var/rudder/ncf/local` is a copy of node-independent directories from - `/var/rudder/configuration-repository/ncf`, so almost everything *BUT* - `/var/rudder/configuration-repository/ncf/50_techniques`. - ** `/var/rudder/ncf/common` is a copy `/usr/share/ncf/tree` -* `/var/rudder/share/xxxx-yyyy-node-id-zzzz/rules/cfengine-community/Technique_Name/1.0/Technique_Name.cf` - for techniques, with one directory for each technique applied to the node. -* `/var/rudder/share/xxxx-yyyy-node-id-zzzz/rules/cfengine-community/rudder_expected_reports.csv` - contains information about report expected for all ncf techniques applied to that node. - -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. - -=== From ncf Technique Editor to Rudder Techniques and back - -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. - -Get request:: - -Get request will get all Techniques and Generic Methods in a path passed as parameters of the -request in the "path" javascript variable: - -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. - -Post requests:: - -Post requests are issued when a Technique is created, modified or deleted. -They will only work on Techniques available in the path given in parameter. - -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. - -=== Hooks - -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. - -- pre-hooks are located in: `/var/rudder/configuration-repository/ncf/pre-hooks.d` -- post-hooks are located in: `/var/rudder/configuration-repository/ncf/post-hooks.d` - -As of March 2015, we have two post-hooks defined and no pre-hooks: - -* `post.write_technique.commit.sh` -** It commits the Technique newly created into Rudder Git configuration repository -located in `/var/rudder/configuration-repository`. -* `post.write_technique.rudderify.sh` -** It generates a valid Rudder Technique from a newly created Technique and reloads Rudder -Technique Library so that updates are taken into account. - -If you want to run post hooks by hand, you can use the following command: - - /var/rudder/configuration-repository/ncf/post-hooks.d/post.write_technique.commit.sh /var/rudder/configuration-repository bundle_name - [[_server_event_hooks]] == Server Event Hooks