Merge branch 'master' into 4.0-pre-not-stable

Signed-off-by: Nico Schottelius <nico@bento.schottelius.org>

Conflicts:
	cdist/config.py
	cdist/emulator.py
	docs/changelog

cdist/conf/type/__apt_key/explorer/state

@@ -0,0 +1,32 @@
+#!/bin/sh
+#
+# 2011-2014 Steven Armstrong (steven-cdist at armstrong.cc)
+#
+# This file is part of cdist.
+#
+# cdist is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# cdist is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with cdist. If not, see <http://www.gnu.org/licenses/>.
+#
+#
+# Get the current state of the apt key.
+#
+
+if [ -f "$__object/parameter/keyid" ]; then
+   keyid="$(cat "$__object/parameter/keyid")"
+else
+   keyid="$__object_id"
+fi
+
+apt-key export "$keyid" | head -n 1 | grep -Fqe "BEGIN PGP PUBLIC KEY BLOCK" \
+   && echo present \
+   || echo absent

cdist/conf/type/__apt_key/gencode-remote

@@ -0,0 +1,42 @@
+#!/bin/sh
+#
+# 2011-2014 Steven Armstrong (steven-cdist at armstrong.cc)
+#
+# This file is part of cdist.
+#
+# cdist is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# cdist is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with cdist. If not, see <http://www.gnu.org/licenses/>.
+#
+
+if [ -f "$__object/parameter/keyid" ]; then
+   keyid="$(cat "$__object/parameter/keyid")"
+else
+   keyid="$__object_id"
+fi
+state_should="$(cat "$__object/parameter/state")"
+state_is="$(cat "$__object/explorer/state")"
+
+if [ "$state_should" = "$state_is" ]; then
+   # nothing to do
+   exit 0
+fi
+
+case "$state_should" in
+   present)
+      keyserver="$(cat "$__object/parameter/keyserver")"
+      echo "apt-key adv --keyserver \"$keyserver\" --recv-keys \"$keyid\""
+   ;;
+   absent)
+      echo "apt-key del \"$keyid\""
+   ;;
+esac

cdist/conf/type/__apt_key/man.text

@@ -0,0 +1,61 @@
+cdist-type__apt_key(7)
+======================
+Steven Armstrong <steven-cdist--@--armstrong.cc>
+
+
+NAME
+----
+cdist-type__apt_key - manage the list of keys used by apt
+
+
+DESCRIPTION
+-----------
+Manages the list of keys used by apt to authenticate packages.
+
+
+REQUIRED PARAMETERS
+-------------------
+None.
+
+
+OPTIONAL PARAMETERS
+-------------------
+state::
+   'present' or 'absent'. Defaults to 'present'
+
+keyid::
+   the id of the key to add. Defaults to __object_id
+
+keyserver::
+   the keyserver from which to fetch the key. If omitted the default set in
+   ./parameter/default/keyserver is used.
+
+
+EXAMPLES
+--------
+
+--------------------------------------------------------------------------------
+# Add Ubuntu Archive Automatic Signing Key
+__apt_key 437D05B5
+# Same thing
+__apt_key 437D05B5 --state present
+# Get rid of it
+__apt_key 437D05B5 --state absent
+
+# same thing with human readable name and explicit keyid
+__apt_key UbuntuArchiveKey --keyid 437D05B5
+
+# same thing with other keyserver
+__apt_key UbuntuArchiveKey --keyid 437D05B5 --keyserver keyserver.ubuntu.com
+--------------------------------------------------------------------------------
+
+
+SEE ALSO
+--------
+- cdist-type(7)
+
+
+COPYING
+-------
+Copyright \(C) 2011-2014 Steven Armstrong. Free use of this software is
+granted under the terms of the GNU General Public License version 3 (GPLv3).

cdist/conf/type/__apt_key/parameter/default/keyserver

@@ -0,0 +1 @@
+subkeys.pgp.net

cdist/conf/type/__apt_key/parameter/default/state

@@ -0,0 +1 @@
+present

cdist/conf/type/__apt_key/parameter/optional

@@ -0,0 +1,3 @@
+state
+keyid
+keyserver

cdist/conf/type/__apt_key_uri/explorer/state

@@ -0,0 +1,32 @@
+#!/bin/sh
+#
+# 2011-2014 Steven Armstrong (steven-cdist at armstrong.cc)
+#
+# This file is part of cdist.
+#
+# cdist is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# cdist is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with cdist. If not, see <http://www.gnu.org/licenses/>.
+#
+#
+# Get the current state of the apt key.
+#
+
+if [ -f "$__object/parameter/name" ]; then
+   name="$(cat "$__object/parameter/name")"
+else
+   name="$__object_id"
+fi
+
+apt-key list | grep -Fqe "$name" \
+   && echo present \
+   || echo absent

cdist/conf/type/__apt_key_uri/gencode-remote

@@ -0,0 +1,45 @@
+#!/bin/sh
+#
+# 2011-2014 Steven Armstrong (steven-cdist at armstrong.cc)
+#
+# This file is part of cdist.
+#
+# cdist is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# cdist is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with cdist. If not, see <http://www.gnu.org/licenses/>.
+#
+
+if [ -f "$__object/parameter/name" ]; then
+   name="$(cat "$__object/parameter/name")"
+else
+   name="$__object_id"
+fi
+state_should="$(cat "$__object/parameter/state")"
+state_is="$(cat "$__object/explorer/state")"
+
+if [ "$state_should" = "$state_is" ]; then
+   # nothing to do
+   exit 0
+fi
+
+case "$state_should" in
+   present)
+      uri="$(cat "$__object/parameter/uri")"
+      printf 'curl -s -L "%s" | apt-key add -\n' "$uri"
+   ;;
+   absent)
+      cat << DONE
+keyid=\$(apt-key list | grep -B1 "$name" | awk '/pub/ { print \$2 }' | cut -d'/' -f 2)
+apt-key del \$keyid
+DONE
+   ;;
+esac

cdist/conf/type/__apt_key_uri/man.text

@@ -0,0 +1,51 @@
+cdist-type__apt_key_uri(7)
+==========================
+Steven Armstrong <steven-cdist--@--armstrong.cc>
+
+
+NAME
+----
+cdist-type__apt_key_uri - add apt key from uri
+
+
+DESCRIPTION
+-----------
+Download a key from an uri and add it to the apt keyring.
+
+
+REQUIRED PARAMETERS
+-------------------
+uri::
+   the uri from which to download the key
+
+
+OPTIONAL PARAMETERS
+-------------------
+state::
+   'present' or 'absent', defaults to 'present'
+
+name::
+   a name for this key, used when testing if it is already installed.
+   Defaults to __object_id
+
+
+EXAMPLES
+--------
+
+--------------------------------------------------------------------------------
+__apt_key_uri rabbitmq \
+   --name 'RabbitMQ Release Signing Key <info@rabbitmq.com>' \
+   --uri http://www.rabbitmq.com/rabbitmq-signing-key-public.asc \
+   --state present
+--------------------------------------------------------------------------------
+
+
+SEE ALSO
+--------
+- cdist-type(7)
+
+
+COPYING
+-------
+Copyright \(C) 2011-2014 Steven Armstrong. Free use of this software is
+granted under the terms of the GNU General Public License version 3 (GPLv3).

cdist/conf/type/__apt_key_uri/manifest

@@ -0,0 +1,21 @@
+#!/bin/sh
+#
+# 2013-2014 Steven Armstrong (steven-cdist at armstrong.cc)
+#
+# This file is part of cdist.
+#
+# cdist is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# cdist is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with cdist. If not, see <http://www.gnu.org/licenses/>.
+#
+
+__package curl

cdist/conf/type/__apt_key_uri/parameter/default/state

@@ -0,0 +1 @@
+present

cdist/conf/type/__apt_key_uri/parameter/optional

@@ -0,0 +1,2 @@
+state
+name

cdist/conf/type/__apt_key_uri/parameter/required

@@ -0,0 +1 @@
+uri

cdist/conf/type/__apt_norecommends/man.text

@@ -0,0 +1,42 @@
+cdist-type__apt_norecommends(7)
+===============================
+Steven Armstrong <steven-cdist--@--armstrong.cc>
+
+
+NAME
+----
+cdist-type__apt_norecommends - configure apt to not install recommended packages
+
+
+DESCRIPTION
+-----------
+Configure apt to not install any recommended or suggested packages.
+
+
+REQUIRED PARAMETERS
+-------------------
+None.
+
+
+OPTIONAL PARAMETERS
+-------------------
+None.
+
+
+EXAMPLES
+--------
+
+--------------------------------------------------------------------------------
+__apt_norecommends
+--------------------------------------------------------------------------------
+
+
+SEE ALSO
+--------
+- cdist-type(7)
+
+
+COPYING
+-------
+Copyright \(C) 2014 Steven Armstrong. Free use of this software is
+granted under the terms of the GNU General Public License version 3 (GPLv3).

cdist/conf/type/__apt_norecommends/manifest

@@ -0,0 +1,42 @@
+#!/bin/sh
+#
+# 2014 Steven Armstrong (steven-cdist at armstrong.cc)
+#
+# This file is part of cdist.
+#
+# cdist is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# cdist is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with cdist. If not, see <http://www.gnu.org/licenses/>.
+#
+
+
+os=$(cat "$__global/explorer/os")
+
+case "$os" in
+   ubuntu|debian)
+      # No stinking recommends thank you very much.
+      # If I want something installed I will do so myself.
+      __file /etc/apt/apt.conf.d/99-no-recommends \
+         --owner root --group root --mode 644 \
+         --source - << DONE
+APT::Install-Recommends "0";
+APT::Install-Suggests "0";
+DONE
+   ;;
+   *)
+      cat >&2 << DONE
+The developer of this type (${__type##*/}) did not think your operating system
+($os) would have any use for it. If you think otherwise please submit a patch.
+DONE
+      exit 1
+   ;;
+esac

cdist/conf/type/__apt_source/files/source.list.template

@@ -0,0 +1,15 @@
+#!/bin/sh
+set -u
+
+entry="$uri $distribution $component"
+cat << DONE
+# Created by cdist ${__type##*/}
+# Do not change. Changes will be overwritten.
+#
+
+# $name
+deb ${forcedarch} $entry
+DONE
+if [ -f "$__object/parameter/include-src" ]; then
+   echo "deb-src $entry"
+fi

cdist/conf/type/__apt_source/man.text

@@ -0,0 +1,69 @@
+cdist-type__apt_source(7)
+=========================
+Steven Armstrong <steven-cdist--@--armstrong.cc>
+
+
+NAME
+----
+cdist-type__apt_source - manage apt sources
+
+
+DESCRIPTION
+-----------
+This cdist type allows you to manage apt sources.
+
+
+REQUIRED PARAMETERS
+-------------------
+uri::
+   the uri to the apt repository
+
+
+OPTIONAL PARAMETERS
+-------------------
+arch::
+   set this if you need to force and specific arch (ubuntu specific)
+
+state::
+   'present' or 'absent', defaults to 'present'
+
+distribution::
+   the distribution codename to use. Defaults to DISTRIB_CODENAME from
+   the targets /etc/lsb-release
+
+component::
+   space delimited list of components to enable. Defaults to an empty string.
+
+
+BOOLEAN PARAMETERS
+------------------
+include-src::
+   include deb-src entries
+
+
+EXAMPLES
+--------
+
+--------------------------------------------------------------------------------
+__apt_source rabbitmq \
+   --uri http://www.rabbitmq.com/debian/ \
+   --distribution testing \
+   --component main \
+   --include-src \
+   --state present
+
+__apt_source canonical_partner \
+   --uri http://archive.canonical.com/ \
+   --component partner --state present
+--------------------------------------------------------------------------------
+
+
+SEE ALSO
+--------
+- cdist-type(7)
+
+
+COPYING
+-------
+Copyright \(C) 2011-2014 Steven Armstrong. Free use of this software is
+granted under the terms of the GNU General Public License version 3 (GPLv3).

cdist/conf/type/__apt_source/manifest

@@ -0,0 +1,56 @@
+#!/bin/sh
+#
+# 2011-2013 Steven Armstrong (steven-cdist at armstrong.cc)
+#
+# This file is part of cdist.
+#
+# cdist is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# cdist is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with cdist. If not, see <http://www.gnu.org/licenses/>.
+#
+
+name="$__object_id"
+state="$(cat "$__object/parameter/state")"
+uri="$(cat "$__object/parameter/uri")"
+
+if [ -f "$__object/parameter/distribution" ]; then
+   distribution="$(cat "$__object/parameter/distribution")"
+else
+   distribution="$(cat "$__global/explorer/lsb_codename")"
+fi
+if [ -f "$__object/parameter/component" ]; then
+   component="$(cat "$__object/parameter/component")"
+else
+   component=""
+fi
+if [ -f "$__object/parameter/arch" ]; then
+   forcedarch="[arch=$(cat "$__object/parameter/arch")]"
+else
+   forcedarch=""
+fi
+
+# export variables for use in template
+export name
+export uri
+export distribution
+export component
+export forcedarch
+
+# generate file from template
+mkdir "$__object/files"
+"$__type/files/source.list.template" > "$__object/files/source.list"
+__file "/etc/apt/sources.list.d/${name}.list" \
+   --source "$__object/files/source.list" \
+   --owner root --group root --mode 0644 \
+   --state "$state"
+
+require="$__object_name" __apt_update_index

cdist/conf/type/__apt_source/parameter/boolean

@@ -0,0 +1 @@
+include-src

cdist/conf/type/__apt_source/parameter/default/state

@@ -0,0 +1 @@
+present

cdist/conf/type/__apt_source/parameter/optional

@@ -0,0 +1,4 @@
+state
+distribution
+component
+arch

cdist/conf/type/__apt_source/parameter/required

@@ -0,0 +1 @@
+uri

cdist/conf/type/__debconf_set_selections/gencode-remote

@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# 2011 Nico Schottelius (nico-cdist at schottelius.org)
+# 2011-2014 Nico Schottelius (nico-cdist at schottelius.org)
 #
 # This file is part of cdist.
 #
@@ -21,6 +21,12 @@
 # Setup selections
 #
 
+filename="$(cat "$__object/parameter/file")"
+
+if [ "$filename" = "-" ]; then
+    filename="$__object/stdin"
+fi
+
 echo "debconf-set-selections << __file-eof"
-cat "$(cat "$__object/parameter/file")"
+cat "$filename"
 echo "__file-eof"

cdist/conf/type/__debconf_set_selections/man.text

@@ -18,6 +18,7 @@ REQUIRED PARAMETERS
 -------------------
 file::
    Use the given filename as input for debconf-set-selections(1)
+   If filename is "-", read from stdin.
 
 
 EXAMPLES
@@ -29,6 +30,10 @@ __debconf_set_selections nslcd --file /path/to/file
 
 # Setup configuration for nslcd from another type
 __debconf_set_selections nslcd --file "$__type/files/preseed/nslcd"
+
+__debconf_set_selections nslcd --file - << eof
+gitolite gitolite/gituser string git
+eof
 --------------------------------------------------------------------------------
 
 
@@ -41,5 +46,5 @@ SEE ALSO
 
 COPYING
 -------
-Copyright \(C) 2011-2013 Nico Schottelius. Free use of this software is
+Copyright \(C) 2011-2014 Nico Schottelius. Free use of this software is
 granted under the terms of the GNU General Public License version 3 (GPLv3).

cdist/conf/type/__jail/gencode-local

@@ -23,7 +23,7 @@
 #
 
 if [ -f "$__object/parameter/jaildir" ]; then
-   jaildir="$(cat "$__object/parameter/name")"
+   jaildir="$(cat "$__object/parameter/jaildir")"
 else
    jaildir="/usr/jail"
 fi

cdist/conf/type/__jail/gencode-remote

@@ -85,7 +85,7 @@ if [ -f "$__object/parameter/onboot" ]; then
 fi
 
 if [ -f "$__object/parameter/jaildir" ]; then
-   jaildir="$(cat "$__object/parameter/name")"
+   jaildir="$(cat "$__object/parameter/jaildir")"
 else
    jaildir="/usr/jail"
 fi

cdist/conf/type/__jail/manifest

@@ -34,7 +34,7 @@ if [ ! "$os" = "freebsd" ]; then
 fi
 
 if [ -f "$__object/parameter/jaildir" ]; then
-   jaildir="$(cat "$__object/parameter/name")"
+   jaildir="$(cat "$__object/parameter/jaildir")"
 else
    jaildir="/usr/jail"
 fi

cdist/conf/type/__process/gencode-remote

@@ -1,6 +1,7 @@
 #!/bin/sh
 #
 # 2011-2012 Nico Schottelius (nico-cdist at schottelius.org)
+# 2014 Steven Armstrong (steven-cdist at armstrong.cc)
 #
 # This file is part of cdist.
 #
@@ -17,7 +18,6 @@
 # You should have received a copy of the GNU General Public License
 # along with cdist. If not, see <http://www.gnu.org/licenses/>.
 #
-#
 
 if [ -f "$__object/parameter/name" ]; then
     name="$(cat "$__object/parameter/name")"
@@ -25,21 +25,18 @@ else
     name="$__object_id"
 fi
 
-parameter_state="$__object/parameter/state"
-if [ -f "$_parameter_state" ]; then
-    state_should=$(cat "$__object/parameter/state")
-else
-    state_should="present"
-fi
+state_should="$(cat "$__object/parameter/state")"
 
-runs="$(cat "$__object/explorer/runs")"
-if [ "$runs" ]; then
+if [ -s "$__object/explorer/runs" ]; then
     state_is="present"
 else
     state_is="absent"
 fi
 
-[ "$state_is" = "$state_should" ] && exit 0
+if [ "$state_is" = "$state_should" ]; then
+   # nothing to do
+   exit 0
+fi
 
 case "$state_should" in
     present)

cdist/conf/type/__process/parameter/default/state

@@ -0,0 +1 @@
+present

cdist/core/cdist_object.py

@@ -2,6 +2,7 @@
 #
 # 2011 Steven Armstrong (steven-cdist at armstrong.cc)
 # 2011-2013 Nico Schottelius (nico-cdist at schottelius.org)
+# 2014 Daniel Heule (hda at sfs.biz)
 #
 # This file is part of cdist.
 #
@@ -211,13 +212,13 @@ class CdistObject(object):
         """Checks wether this cdist object exists on the file systems."""
         return os.path.exists(self.absolute_path)
 
-    def create(self):
+    def create(self, allow_overwrite=False):
         """Create this cdist object on the filesystem.
         """
         try:
-            os.makedirs(self.absolute_path, exist_ok=False)
+            os.makedirs(self.absolute_path, exist_ok=allow_overwrite)
             absolute_parameter_path = os.path.join(self.base_path, self.parameter_path)
-            os.makedirs(absolute_parameter_path, exist_ok=False)
+            os.makedirs(absolute_parameter_path, exist_ok=allow_overwrite)
         except EnvironmentError as error:
             raise cdist.Error('Error creating directories for cdist object: %s: %s' % (self, error))
 

cdist/emulator.py

@@ -2,6 +2,7 @@
 #
 # 2011-2013 Nico Schottelius (nico-cdist at schottelius.org)
 # 2012-2013 Steven Armstrong (steven-cdist at armstrong.cc)
+# 2014 Daniel Heule (hda at sfs.biz)
 #
 # This file is part of cdist.
 #
@@ -144,11 +145,15 @@ class Emulator(object):
             if value is not None:
                 self.parameters[key] = value
 
-        if self.cdist_object.exists:
+        if self.cdist_object.exists and not 'CDIST_ALLOW_OVERRIDE' in os.environ:
             if self.cdist_object.parameters != self.parameters:
                 raise cdist.Error("Object %s already exists with conflicting parameters:\n%s: %s\n%s: %s"
                     % (self.cdist_object.name, " ".join(self.cdist_object.source), self.cdist_object.parameters, self.object_source, self.parameters)
             )
+        else:
+            if self.cdist_object.exists:
+                self.log.debug('Object %s override forced with CDIST_ALLOW_OVERRIDE',self.cdist_object.name)
+                self.cdist_object.create(True)
             else:
                 self.cdist_object.create()
             self.cdist_object.parameters = self.parameters

docs/changelog

@@ -8,8 +8,29 @@ Changelog
 	* Core: Integrate initial install support
 	* Core: Integrate initial preos support
 
-3.0.4:
+
+3.0.6:
+	* New Type: __apt_key (Steven Armstrong)
+	* New Type: __apt_key_uri (Steven Armstrong)
+	* New Type: __apt_norecommends (Steven Armstrong)
+	* New Type: __apt_source (Steven Armstrong)
+
+
+3.0.5: 2014-02-05
+	* Core: Introduce override concept (Daniel Heule)
+	* Type __process: Make --state absent work (Steven Armstrong)
+	* Documentation: Update documentation for environment variables
+
+
+3.0.4: 2014-01-29
+	* Core: Ignore install types in config mode
+	* Documentation: Update reference (files path in object space)
+	* Documentation: Update best practise: Replaces templates/ with files/
+>>>>>>> master
 	* Type __apt_ppa: Install required software (Steven Armstrong)
+	* Type __debconf_set_selections: Support --file - to read from stdin
+	* Type __jail: Fix jaildir parameter handling (Jake Guffey)
+
 
 3.0.3: 2014-01-22
 	* Core: Enhance error message when requirement is missing object id
@@ -23,6 +44,7 @@ Changelog
 	* Type __zypper_repo: Use default paremeters (Daniel Heule)
 	* Type __zypper_service: Use default paremeters (Daniel Heule)
 
+
 3.0.2: 2014-01-19
 	* Documentation: Document all messages sent by types (Daniel Heule)
 	* New Type: __block (Steven Armstrong)

docs/man/cdist-reference.text.sh

@@ -131,7 +131,8 @@ confdir/type/<name>/explorer::
 
 confdir/type/<name>/files::
     This directory is reserved for user data and will not be used
-    by cdist at any time
+    by cdist at any time. It can be used for storing supplementary
+    files (like scripts to act as a template or configuration files).
 
 out/::
     This directory contains output of cdist and is usually located
@@ -175,13 +176,22 @@ OBJECTS
 For object to object communication and tests, the following paths are
 usable within a object directory:
 
+files::
+    This directory is reserved for user data and will not be used
+    by cdist at any time. It can be used freely by the type 
+    (for instance to store template results).
 changed::
     This empty file exists in an object directory, if the object has
     code to be excuted (either remote or local)
+stdin::
+    This file exists and contains data, if data was provided on stdin 
+    when the type was called.
 
 
-ENVIRONMENT VARIABLES
----------------------
+ENVIRONMENT VARIABLES (FOR READING)
+-----------------------------------
+The following environment variables are exported by cdist:
+
 __explorer::
     Directory that contains all global explorers.
     Available for: initial manifest, explorer, type explorer, shell
@@ -219,6 +229,15 @@ __type_explorer::
     Directory that contains the type explorers.
     Available for: type explorer
 
+ENVIRONMENT VARIABLES (FOR WRITING)
+-----------------------------------
+The following environment variables influence the behaviour of cdist:
+
+require::
+    Setup dependencies between objects (see cdist-manifest(7))
+
+CDIST_ALLOW_OVERRIDE::
+    Allow overwriting type parameters (see cdist-manifest(7))
 
 SEE ALSO
 --------

docs/man/man7/cdist-best-practice.text

@@ -164,8 +164,8 @@ For more details consult sudoers(5)
 
 TEMPLATING
 ----------
-* create directory templates/ in your type (convention)
-* create the template as an executable file like templates/basic.conf.sh, it will output text using shell variables for the values
+* create directory files/ in your type (convention)
+* create the template as an executable file like files/basic.conf.sh, it will output text using shell variables for the values
 
 --------------------------------------------------------------------------------
 #!/bin/sh
@@ -191,7 +191,7 @@ EOF
   export ROOT='/var/www/test'
 # render the template
   mkdir -p "$__object/files"
-  "$__type/templates/basic.conf.sh" > "$__object/files/basic.conf"
+  "$__type/files/basic.conf.sh" > "$__object/files/basic.conf"
 # send the rendered template
   __file /etc/nginx/sites-available/test.conf  \
     --state present

docs/man/man7/cdist-manifest.text

@@ -129,6 +129,19 @@ from the type that is calling them. This is called "autorequirement" in
 cdist jargon.
 
 
+OVERRIDES
+---------
+In some special cases, you would like to create an already defined object 
+with different parameters. In normal situations this leads to an error in cdist.
+If you whish, you can setup the environment variable CDIST_ALLOW_OVERRIDE
+(any value or even empty is ok) to tell cdist, that this object override is 
+wanted and should be accepted.
+ATTENTION: Only use this feature if you are 100% sure in which order 
+cdist encounter the affected objects, otherwhise this results 
+into an undefined situation. 
+
+THIS IS A BETA FEATURE AND MAY BE REMOVED AT ANY TIME.
+
 EXAMPLES
 --------
 The initial manifest may for instance contain the following code:
@@ -161,6 +174,26 @@ __package lighttpd --state present
 require="__package/lighttpd" __package munin --state present
 --------------------------------------------------------------------------------
 
+How to override objects:
+
+--------------------------------------------------------------------------------
+# for example in the inital manifest
+
+# reate user account foobar with some hash for password
+__user foobar --password 'some_fancy_hash' --home /home/foobarexample
+
+# ... many statements and includes in the manifest later ...
+# somewhere in a conditionaly sourced manifest 
+# (e.g. for example only sourced if a special application is on the target host)
+
+# this leads to an error ...
+__user foobar --password 'some_other_hash' 
+
+# this tells cdist, that you know that this is an override and should be accepted
+CDIST_ALLOW_OVERRIDE=yes __user foobar --password 'some_other_hash'
+# its only an override, means the parameter --home is not touched 
+# and stay at the original value of /home/foobarexample
+--------------------------------------------------------------------------------
 
 
 SEE ALSO