From 5e00ac702a5d65141afc9e4b3409120546be7f66 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Tue, 17 Jan 2012 21:57:32 +0100 Subject: [PATCH] finish rewrite of cdist-manifest Signed-off-by: Nico Schottelius --- doc/man/man7/cdist-manifest.text | 127 ++++++++++++++++++++----------- 1 file changed, 82 insertions(+), 45 deletions(-) diff --git a/doc/man/man7/cdist-manifest.text b/doc/man/man7/cdist-manifest.text index 917ea697..1f0e253d 100644 --- a/doc/man/man7/cdist-manifest.text +++ b/doc/man/man7/cdist-manifest.text @@ -5,14 +5,38 @@ Nico Schottelius NAME ---- -cdist-manifest - Using types +cdist-manifest - (Re-)Use types + DESCRIPTION ----------- -Manifests exist to define which configurations should be applied to a specific -host as well as to define which configurations should be applied within a -type. Manifests are executed locally and the resulting objects are stored in -an internal database. +Manifests are used to define which objects to create. +Objects are instances of **types**, like in object orientated programming languages. +An object is represented by the combination of +**type + slash + object name**: **__file/etc/cdist-configured** is an +object of the type ***__file*** with the name ***etc/cdist-configured***. + +All available types can be found in the **conf/type/** directory, +use **ls conf/type** to get the list of available types. If you have +setup the MANPATH correctly, you can use **man cdist-reference** to access +the reference with pointers to the manpages. + + +Types in manifests are used like normal command line tools. Let's have a look +at an example: +-------------------------------------------------------------------------------- +# Create object of type __package with the parameter state = removed +__package apache2 --state removed + +# Same with the __directory type + __directory /tmp/cdist --state present +-------------------------------------------------------------------------------- + +These two lines create objects, which will later be used to realise the +configuration on the target host. + +Manifests are executed locally as a shell script using **/bin/sh -e**. +The resulting objects are stored in an internal database. The same object can be redefined in multiple different manifests as long as the parameters are exactly the same. @@ -21,17 +45,19 @@ In general, manifests are used to define which types are used depending on given conditions. +INITIAL AND TYPE MANIFESTS +-------------------------- +Cdist nows about two types of manifests: The initial manifest and type +manifests. The initial manifest is used to define, which configurations +to apply to which hosts. The type manifests are used to create objects +from types. More about manifests in types can be found in cdist-type(7). + + DEFINE STATE IN THE INITIAL MANIFEST ------------------------------------ The **initial manifest** is the entry point for cdist to find out, which -**objects** to configure on the selected host. Objects are instances of -**types**, like in object orientated programming languages. -An object is represented by the -type + slash + object name: ***__file/etc/cdist-configured*** is an -object of the type ***__file*** with the name ***etc/cdist-configured***. - -Cdist searches for the initial manifest at **conf/manifest/init** and -executes it as a shell script using **/bin/sh -e**. +**objects** to configure on the selected host. +Cdist searches for the initial manifest at **conf/manifest/init**. Within this initial manifest, you define, which objects should be created on which host. To distinguish between hosts, you can use the @@ -56,15 +82,51 @@ is only created on the host ***localhost***. As you can see, there is no magic involved, the manifest is simple shell code that utilises cdist types. Every available type can be executed like a normal -command. Use **ls conf/type** to get a list of available types. If you have -setup the MANPATH correctly as, you can use **man cdist-reference** to access -the reference with pointers to the manpages. +command. -INITIAL VS. TYPE MANIFEST -------------------------- -MANAGING YOUR OWN CONFIGURATION +SPLITTING UP THE INITIAL MANIFEST +--------------------------------- +If you want to split up your initial manifest, you can create other shell +scripts in **conf/manifest/** and include them in **conf/manifest/init**. +Cdist provides the environment variable ***__manifest*** to reference to +the directory containing the initial manifest (see cdist-reference(7)). +The following example would include every file with a **.sh** suffix: + +-------------------------------------------------------------------------------- +# Include *.sh +for manifest in $__manifest/*.sh; do + # And source scripts into our shell environment + . "$manifest" +done +-------------------------------------------------------------------------------- + + +DEPENDENCIES +------------ +If you want to describe that something requires something else, just +setup the variable "require" to contain the requirements. Multiple +requirements can be added white space seperated. + +-------------------------------------------------------------------------------- +# No dependency +__file /etc/cdist-configured + +# Require above object +require="__file/etc/cdist-configured" __link /tmp/cdist-testfile \ + --source /etc/cdist-configured --type symbolic + +# Require two objects +require="__file/etc/cdist-configured __link/tmp/cdist-testfile" \ + __file /tmp/cdist-another-testfile + + +-------------------------------------------------------------------------------- + +All objects that are created in a type manifest are automatically required +from the type that is calling them. This is called "autorequirement" in +cdist jargon. EXAMPLES @@ -89,36 +151,11 @@ The manifest of the type "nologin" may look like this: __file /etc/nologin --type file --source "$__type/files/default.nologin" -------------------------------------------------------------------------------- -DEPENDENCIES ------------- -If you want to describe that something requires something else, just -setup the variable "require" to contain the requirements. Multiple -requirements can be added white space seperated. - - --------------------------------------------------------------------------------- -# No dependency -__file /etc/cdist-configured - -# Require above object -require="__file/etc/cdist-configured" __link /tmp/cdist-testfile \ - --source /etc/cdist-configured --type symbolic - -# Require two objects -require="__file/etc/cdist-configured __link/tmp/cdist-testfile" \ - __file /tmp/cdist-another-testfile - - --------------------------------------------------------------------------------- - -If you do not specify - -FIXME: autorequire SEE ALSO -------- -- cdist-type(7) - cdist-tutorial(7) +- cdist-type(7) COPYING