diff --git a/doc/man/cdist-stages.text b/doc/man/cdist-stages.text index 960813f6..f82f9046 100644 --- a/doc/man/cdist-stages.text +++ b/doc/man/cdist-stages.text @@ -5,77 +5,82 @@ Nico Schottelius NAME ---- -cdist-stages - How the configuration is built +cdist-stages - Stages used during configuration deployment DESCRIPTION ----------- -Starting the execution of deployment with cdist-deploy-to(1), -cdist passes through different stages, each can be triggered -and debugged on its own. Reading the source of the -cdist-deploy-to script shous the binaries being responsible -for each stage. +Starting the execution of deployment with cdist-deploy-to(1), cdist passes +through different stages, each can be triggered and debugged on its own. +Reading the source of the cdist-deploy-to executable shous the scripts +responsible for each stage. + STAGE 1: TARGET INFORMATION RETRIEVAL -------------------------------------- -In this stage information is collected about target using -so called explorers. -Every existing explorer is run on the target and the output -of all explorers are copied back into the local cache. -The results can be used by manifests and types. +In this stage information is collected about target using so called explorers. +Every existing explorer is run on the target and the output of all explorers +are copied back into the local cache. The results can be used by manifests and +types. Related manpages are cdist-explorers(7) and cdist-cache(7). STAGE 2: RUN THE INITIAL MANIFEST --------------------------------- -The initial manifest, which should be used for mappings -of hosts to types, is executed. - -This stage creates objects in a cconfig database that -contains as defined in the manifest for the specific host. - -In this stage, no conflicts may occur, i.e. no object of -the same type with the same id may be created. +The initial manifest, which should be used for mappings of hosts to types, +is executed. This stage creates objects in a cconfig database that contains +the objects as defined in the manifest for the specific host. In this stage, +no conflicts may occur, i.e. no object of the same type with the same id may +be created. Related manpages are cdist-manifest-init(1), cdist-manifests(7) and cdist-config-layout(7). + STAGE 3: EXECUTION OF TYPES --------------------------- -Every object is checked whether its type has an init -script (see cdist-types(7)). If the type of the object -has an init script, it is run. This init script may -generate additional objects. +Every object is checked whether its type has a manifest file. If the type has +a manifest file and it is executable, it will be executed. The manifest script +may generate and change the created objects. In other words, one type can reuse +other types. -For instance the object __apache/www.test.ch is of -type __apache, which may contain an init script, which -creates new objects of type __file. +For instance the object __apache/www.test.ch is of type __apache, which may +contain an manifest script, which creates new objects of type __file. + +The newly created objects are merged back into the existing tree. No conflicts +may occur during the merge. A conflict would mean that two different objects +try to create the same object, which indicates a broken configuration. + +Related manpage are cdist-types(7) and cdist-manifest-run-all(1). -The newly created objects are merged back into -the existing tree. No conflicts may occur during -the merge. A conflict would mean that two different -objects try to create the same object, which indicates a -broken configuration. STAGE 4: CODE GENERATION ------------------------ -The "gencode" binary of the types for every existing object is -called to generate code that will be executed on the target host. +In this stage for every created objects its type is checked whether it has a +gencode script. If the type has a gencode script and it is executable it will +be executed. This executable should create code to be executed on the target +on stdout. If the gencode executable fails, it must print diagnostic messages +on stderr and exit non-zero. -This binary should create code to be executed on the target on stdout. +Related manpages are cdist-types-gencode(7), cdist-gencode(1) and +cdist-gencode-all(1). -If the gencode binary fails, it must print diagnostic messages on stderr -and exit non-zero. - -A description of what the generated code may/must/should -do can be found in cdist-types-gencode(7). STAGE 5: CODE EXECUTION ----------------------- +The resulting code from the previous stage is transferred to the target host +and executed there to apply the configuration changes, -The resulting code is transferred to the target host and executed, -the run of cdist-deploy-to(1) ends. +Related manpages are cdist-exec-transfer(1) and cdist-exec-run(1). + + +SUMMARY +------- +If, and only if, all the stages complete without an errors, the configuration +will be applied to the target. Each stage can also be run individually, though +dependencies for each stage must be fulfilled and thus the stages must be run +in correct order. SEE ALSO