cdist-backup/doc/man/cdist-stages.text

cdist-stages(7)
===============
Nico Schottelius <nico-cdist--@--schottelius.org>
Steven Armstrong <steven-dist--@--armstrong.cc>


NAME
----
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 and cdist-object-run-all executables
shows the scripts responsible for each stage.


STAGE 0: INTERNAL PREPERATION
-----------------------------
Before running the user facing stages, cdist prepares the target host
to contain cdist binaries and creates a clean environment for the
configuration run.

Related documentation:
   - cdist-bin-transfer(1) FIXME: does not exist


STAGE 1: TARGET INFORMATION RETRIEVAL
--------------------------------------
In this stage information is collected about the target host 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 documentation:
   - cdist-explorer-run-global(1)
   - cdist-remote-explorer-run(1)
   - cdist-explorer(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
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 documentation: 
   - cdist-manifest-run-init(1)
   - cdist-manifest-run(1)
   - cdist-manifest(7)


STAGE 3: OBJECT INFORMATION RETRIEVAL
-------------------------------------
Every object is checked whether its type has explorers and if so, these are 
transfered to the target host and executed. The results are transfered back
and can be used in the following stages to decide what changes need to made
on the target to implement the desired state.

Related documentation:
   - cdist-object-explorer-run(1)
   - cdist-remote-explorer-run(1)
   - cdist-type(7) 
   - cdist-explorer(7)


STAGE 4: RUN THE OBJECT MANIFEST
--------------------------------
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 a 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 documentation:
   - cdist-object-manifest-run(1)
   - cdist-manifest-run(1)
   - cdist-type(7) 


STAGE 5: CODE GENERATION
------------------------
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.

Related documentation:
   - cdist-object-gencode-run(1)
   - cdist-object-gencode(1)
   - cdist-type(7) 


STAGE 6: CODE EXECUTION
-----------------------
For every object the resulting code from the previous stage is transferred to
the target host and executed there to apply the configuration changes.

Related documentation:
   - cdist-object-code-run(1)
   - cdist-code-run(1)


STAGE 7: CACHE
--------------
The cache stores the information from the current run for later use.

Related documentation:
   - cdist-cache(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
--------
- cdist(7)
- cdist-deploy-to(1)
- cdist-reference(7)


COPYING
-------
Copyright \(C) 2010-2011 Nico Schottelius, Steven Armstrong. Free use of this software is
granted under the terms of the GNU General Public License version 3 (GPLv3).