cdist - Configuration management
cdist [-h] [-V]
cdist banner
cdist config [-h] [-d] [-V] [-c CONF_DIR] [-i MANIFEST] [-p] [-s] host [host …]
cdist is the frontend executable to the cdist configuration management.
+cdist supports different as explained below. The options to the main
+program are:
-
+-h, --help
+
-
+ Show the help screen
+
-
+-V, --version
+
-
+ Show version and exit
+
Displays the cdist banner.
Configure a system
-
+-h, --help
+
-
+ Show the help screen
+
-
+-c CONF_DIR, --conf-dir CONF_DIR
+
-
+ Add a configuration directory. Can be specified multiple times.
+ If configuration directories contain conflicting types, explorers or
+ manifests, then the last one found is used. Additionally this can also
+ be configured by setting the CDIST_PATH environment variable to a colon
+ delimited list of config directories. Directories given with the
+ --conf-dir argument have higher precedence over those set through the
+ environment variable.
+
-
+-d, --debug
+
-
+ Enable debug output
+
-
+-i MANIFEST, --initial-manifest MANIFEST
+
-
+ Path to a cdist manifest or - to read from stdin
+
-
+-p, --parallel
+
-
+ Operate on multiple hosts in parallel
+
-
+-s, --sequential
+
-
+ Operate on multiple hosts sequentially
+
--remote-copy REMOTE_COPY:
+ Command to use for remote copy (should behave like scp)
--remote-exec REMOTE_EXEC:
+ Command to use for remote execution (should behave like ssh)
# Configure ikq05.ethz.ch with debug enabled
+cdist config -d ikq05.ethz.ch
+
+# Configure hosts in parallel and use a different configuration directory
+cdist config -c ~/p/cdist-nutzung \
+ -p ikq02.ethz.ch ikq03.ethz.ch ikq04.ethz.ch
+
+# Use custom remote exec / copy commands
+cdist config --remote-exec /path/to/my/remote/exec \
+ --remote-copy /path/to/my/remote/copy \
+ -p ikq02.ethz.ch ikq03.ethz.ch ikq04.ethz.ch
+
+# Display banner
+cdist banner
+
+# Show help
+cdist --help
+
+# Show Version
+cdist --version
The following exit values shall be returned:
-
+0
+
-
+ Successful completion
+
-
+1
+
-
+ One or more host configurations failed
+
-
+cdist(7)
+
-
+cdist-reference(7)
+
Copyright (C) 2011-2012 Nico Schottelius. Free use of this software is
+granted under the terms of the GNU General Public License version 3 (GPLv3).
cdist-best-practice - Practices used in real environments
2. PASSWORDLESS CONNECTIONS
It is recommended to run cdist with public key authentication.
+This requires a private/public key pair and the entry
+"PermitRootLogin without-password" in the sshd server.
+See sshd_config(5) and ssh-keygen(1).
3. SPEEDING UP SSH CONNECTIONS
When connecting to a new host, the initial delay with ssh connections
+is pretty big. You can work around this by
+"sharing of multiple sessions over a single network connection"
+(quote from ssh_config(5)). The following code is suitable for
+inclusion into your ~/.ssh/config:
Host *
+ ControlPath ~/.ssh/master-%l-%r@%h:%p
+ ControlMaster auto
+ ControlPersist 10
4. SPEEDING UP SHELL EXECUTION
On the source host, ensure that /bin/sh is not bash: bash is quite slow for
+script execution. Instead, you could use dash after installing it:
ln -sf /bin/dash /bin/sh
5. MULTI MASTER OR ENVIRONMENT SETUPS
If you plan to distribute cdist among servers or use different
+environments, you can do so easily with the included version
+control git. For instance if you plan to use the typical three
+environments production, integration and development, you can
+realise this with git branches:
# Go to cdist checkout
+cd /path/to/cdist
+
+# Create branches
+git branch development
+git branch integration
+git branch production
+
+# Make use of a branch, for instance production
+git checkout production
Similar if you want to have cdist checked out at multiple machines,
+you can clone it multiple times:
machine-a % git clone git://your-git-server/cdist
+machine-b % git clone git://your-git-server/cdist
6. SEPERATING WORK BY GROUPS
If you are working with different groups on one cdist-configuration,
+you can delegate to other manifests and have the groups edit only
+their manifests. You can use the following snippet in
+conf/manifests/init:
# Include other groups
+sh -e "$__manifest/systems"
+
+sh -e "$__manifest/cbrg"
7. MAINTAINING MULTIPLE CONFIGURATIONS
When you need to manage multiple sites with cdist, like company_a, company_b
+and private for instance, you can easily use git for this purpose.
+Including a possible common base that is reused accross the different sites:
# create branches
+git branch company_a company_b common private
+
+# make stuff for company a
+git checkout company_a
+# work, commit, etc.
+
+# make stuff for company b
+git checkout company_b
+# work, commit, etc.
+
+# make stuff relevant for all sites
+git checkout common
+# work, commit, etc.
+
+# change to private and include latest common stuff
+git checkout private
+git merge common
The following .git/config is taken from a a real world scenario:
# Track upstream, merge from time to time
+[remote "upstream"]
+ url = git://git.schottelius.org/cdist
+ fetch = +refs/heads/*:refs/remotes/upstream/*
+
+# Same as upstream, but works when being offline
+[remote "local"]
+ fetch = +refs/heads/*:refs/remotes/local/*
+ url = /home/users/nico/p/cdist
+
+# Remote containing various ETH internal branches
+[remote "eth"]
+ url = sans.ethz.ch:/home/services/sans/git/cdist-eth
+ fetch = +refs/heads/*:refs/remotes/eth/*
+
+# Public remote that contains my private changes to cdist upstream
+[remote "nico"]
+ url = git.schottelius.org:/home/services/git/cdist-nico
+ fetch = +refs/heads/*:refs/remotes/nico/*
+
+# The "nico" branch will be synced with the remote nico, branch master
+[branch "nico"]
+ remote = nico
+ merge = refs/heads/master
+
+# ETH stable contains rock solid configurations used in various places
+[branch "eth-stable"]
+ remote = eth
+ merge = refs/heads/stable
Have a look at git-remote(1) to adjust the remote configuration, which allows
8. MULTIPLE DEVELOPERS WITH DIFFERENT TRUST
If you are working in an environment that requires different people to
+work on the same configuration, but having different privileges, you can
+implement this scenario with a gateway host and sudo:
-
+Create a dedicated user (for instance cdist)
+
-
+Setup the ssh-pubkey for this user that has the right to configure all hosts
+
-
+Create a wrapper to update the cdist configuration in ~cdist/cdist
+
-
+Allow every developer to execute this script via sudo as the user cdist
+
-
+Allow run of cdist as user cdist on specific hosts on a per user/group base
+
-
+f.i. nico ALL=(ALL) NOPASSWD: /home/cdist/bin/cdist config hostabc
+
For more details consult sudoers(5)
-
+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
+
#!/bin/sh
+# in the template, use cat << eof (here document) to output the text
+# and use standard shell variables in the template
+# output everything in the template script to stdout
+cat << EOF
+server {
+ listen 80;
+ server_name $SERVERNAME;
+ root $ROOT;
+
+ access_log /var/log/nginx/$SERVERNAME_access.log
+ error_log /var/log/nginx/$SERVERNAME_error.log
+}
+EOF-
+in the manifest, export the relevant variables and add the following lines in your manifest:
+
# export variables needed for the template
+ export SERVERNAME='test"
+ export ROOT='/var/www/test'
+# render the template
+ mkdir -p "$__object/files"
+ "$__type/templates/basic.conf.sh" > "$__object/files/basic.conf"
+# send the rendered template
+ __file /etc/nginx/sites-available/test.conf --state present --source "$__object/files/basic.conf"
-
+cdist(1)
+
-
+cdist-tutorial(7)
+
Copyright (C) 2011-2012 Nico Schottelius. Free use of this software is
+granted under the terms of the GNU General Public License version 3 (GPLv3).
cdist-bootstrap - setup cdist environment
This document describes the usual steps recommended for a new
+cdist setup. It is recommended that you have read and understood
+cdist-quickstart(7) before digging into this.
First of all, you should think about where to store your configuration
+database and who will be accessing or changing it. Secondly you have to
+think about where to configure your hosts from, which may be a different
+location.
For starters, having cdist (which includes the configuration database) on
+your notebook should be fine.
+Additionally an external copy of the git repository the configuration
+relies in is recommended, for use as backup as well to allow easy collaboration
+with others.
For more sophisticated setups developing cdist configurations with multiple
+people, have a look at cdist-best-practice(7).
4. SETUP WORKING DIRECTORY AND BRANCH
I assume you have a fresh copy of the cdist tree in ~/cdist, cloned from
+one of the official urls (see cdist-quickstart(7) if you don’t).
+Entering the command "git branch" should show you "* master", which indicates
+you are on the master branch.
The master branch reflects the latest development of cdist. As this is the
+development branch, it may or may not work. There are also version branches
+available, which are kept in a stable state. Let’s use git branch -r
+to list all branches:
cdist% git branch -r
+ origin/1.0
+ origin/1.1
+ origin/1.2
+ origin/1.3
+ origin/1.4
+ origin/1.5
+ origin/1.6
+ origin/1.7
+ origin/2.0
+ origin/HEAD -> origin/master
+ origin/archive_shell_function_approach
+ origin/master
So 2.0 is the latest version branch in this example.
+All versions (2.0.x) within one version branch (2.0) are compatible to each
+other and won’t break your configuration when updating.
It’s up to you to decide which branch you want to base your own work on:
+master contains more recent changes, newer types, but may also break.
+The version branches are stable, but may lack the latest features.
+Your decision can be changed later on, but may result in merge conflicts,
+which you will need to solve.
Let’s assume you want latest stuff and select the master branch as base for
+your own work. Now it’s time to create your branch, which contains your
+local changes. I usually name it by the company/area I am working for:
+ethz-systems, localch, customerX, … But this is pretty much up to you.
In this tutorial I use the branch mycompany:
cdist% git checkout -b mycompany origin/master
+Branch mycompany set up to track remote branch master from origin.
+Switched to a new branch 'mycompany'
+cdist-user% git branch
+ master
+* mycompany
From now on, you can use git as usual to commit your changes in your own branch.
5. PUBLISHING THE CONFIGURATION
Usually a development machine like a notebook should be considered
+temporary only. For this reason and to enable shareability, the configuration
+should be published to another device as early as possible. The following
+example shows how to publish the configuration to another host that is
+reachable via ssh and has git installed:
# Create bare git repository on the host named "loch"
+cdist% ssh loch "GIT_DIR=/home/nutzer/cdist git init"
+Initialized empty Git repository in /home/nutzer/cdist/
+
+# Add remote git repo to git config
+cdist% git remote add loch loch:/home/nutzer/cdist
+
+# Configure the mycompany branch to push to loch
+cdist% git config branch.mycompany.remote loch
+
+# Configure mycompany branch to push into remote master branch
+cdist% git config branch.mycompany.merge refs/heads/master
+
+# Push mycompany branch to remote branch master initially
+cdist% git push loch mycompany:refs/heads/master
Now you have setup the git repository to synchronise the mycompany
+branch with the master branch on the host loch. Thus you can commit
+as usual in your branch and push out changes by entering git push.
Whenever you want to update your cdist installation, you can use git to do so:
# Update git repository with latest changes from origin
+cdist% git fetch origin
+
+# Update current branch with master branch from origin
+cdist% git merge origin/master
+
+# Alternative: Update current branch with 2.0 branch from origin
+cdist% git merge origin/2.0
-
+cdist(1)
+
-
+cdist-tutorial(7)
+
Copyright (C) 2012 Nico Schottelius. Free use of this software is
+granted under the terms of the GNU General Public License version 3 (GPLv3).
cdist-explorer - Explore the target systems
Explorer are small shell scripts, which will be executed on the target
+host. The aim of the explorer is to give hints to types on how to act on the
+target system. An explorer outputs the result to stdout, which is usually
+a one liner, but may be empty or multi line especially in the case of
+type explorers.
There are general explorers, which are run in an early stage, and
+type explorers. Both work almost exactly the same way, with the difference
+that the values of the general explorers are stored in a general location and
+the type specific below the object.
Explorers can reuse other explorers on the target system by calling
+$explorer/<explorer_name> (general and type explorer) or
+$type_explorer/<explorer name> (type explorer).
In case of significant errors, the explorer may exit non-zero and return an
+error message on stderr, which will cause cdist to abort.
You can also use stderr for debugging purposes while developing a new
+explorer.
A very simple explorer may look like this:
hostname
Which is in practise the hostname explorer.
A type explorer, which could check for the status of a package may look like this:
if [ -f "$__object/parameter/name" ]; then
+ name="$(cat "$__object/parameter/name")"
+else
+ name="$__object_id"
+fi
+
+# Except dpkg failing, if package is not known / installed
+dpkg -s "$name" 2>/dev/null || exit 0
-
+cdist(1)
+
-
+cdist-reference(7)
+
-
+cdist-stages(7)
+
Copyright (C) 2010-2012 Nico Schottelius. Free use of this software is
+granted under the terms of the GNU General Public License version 3 (GPLv3).
cdist-hacker - How to get (stuff) into cdist
Welcome dear hacker! I invite you to a tour of pointers to
+get into the usable configuration mangament system, cdist.
The first thing to know is probably that cdist is brought to
+you by people who care about how code looks like and who think
+twice before merging or implementing a feature: Less features
+with good usability are far better than the opposite.
If you believe you’ve found a bug and verified that it is
+in the latest version, drop a mail to the cdist mailing list,
+subject prefixed with "[BUG] " or create an issue on github.
4. CODING CONVENTIONS (EVERYWHERE)
If something should be better done or needs to fixed, add the word FIXME
+nearby, so grepping for FIXME gives all positions that need to be fixed.
Indention is 4 spaces (welcome to the python world).
5. HOW TO SUBMIT STUFF FOR INCLUSION INTO UPSTREAM CDIST
If you did some cool changes to cdist, which you value as a benefit for
+everybody using cdist, you’re welcome to propose inclusion into upstream.
There are though some requirements to ensure your changes don’t break others
+work nor kill the authors brain:
-
+All files should contain the usual header (Author, Copying, etc.)
+
-
+Code submission must be done via git
+
-
+Do not add cdist/conf/manifest/init - This file should only be touched in your
+ private branch!
+
-
+Code to be included should be branched of the upstream "master" branch
+
-
+Exception: Bugfixes to a version branch
+
-
+On a merge request, always name the branch I should pull from
+
-
+Always ensure all manpages build. Use ./build man to test.
+
-
+If you developed more than one feature, consider submitting them in
+ separate branches. This way one feature can already be included, even if
+ the other needs to be improved.
+
As soon as your work meets these requirements, write a mail
+for inclusion to the mailinglist cdist at cdist — at — l.schottelius.org
+or open a pull request at http://github.com/telmich/cdist.
6. HOW TO SUBMIT A NEW TYPE
For detailled information about types, see cdist-type(7).
Submitting a type works as described above, with the additional requirement
+that a corresponding manpage named man.text in asciidoc format with
+the manpage-name "cdist-type__NAME" is included in the type directory
+AND asciidoc is able to compile it (i.e. do NOT have to many "=" in the second
+line).
Warning: Submitting "exec" or "run" types that simply echo their parameter in
+gencode* will not be accepted, because they are of no use. Every type can output
+code and thus such a type introduces redundant functionality that is given by
+core cdist already.
Copyright (C) 2011-2012 Nico Schottelius. Free use of this software is
+granted under the terms of the GNU General Public License version 3 (GPLv3).
cdist-manifest - (Re-)Use types
Manifests are used to define which objects to create.
+Objects are instances of types, like in object oriented 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 cdist/conf/type/ directory,
+use ls cdist/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.
In general, manifests are used to define which types are used depending
+on given conditions.
3. INITIAL AND TYPE MANIFESTS
Cdist knows 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).
4. 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.
+Cdist expects the initial manifest at cdist/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
+environment variable __target_host. Let’s have a look at a simple
+example:
__cdistmarker
+
+case "$__target_host" in
+ localhost)
+ __directory /home/services/kvm-vm --parents yes
+ ;;
+esac
This manifest says: Independent of the host, always use the type
+__cdistmarker, which creates the file /etc/cdist-configured,
+with the timestamp as content.
+The directory /home/services/kvm-vm, including all parent directories,
+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.
5. SPLITTING UP THE INITIAL MANIFEST
If you want to split up your initial manifest, you can create other shell
+scripts in cdist/conf/manifest/ and include them in cdist/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
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 separated.
# 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.
The initial manifest may for instance contain the following code:
# Always create this file, so other sysadmins know cdist is used.
+__file /etc/cdist-configured --type file
+
+case "$__target_host" in
+ my.server.name)
+ __file /root/bin/ --type directory
+ __file /etc/issue.net --type file --source "$__manifest/issue.net
+ ;;
+esac
The manifest of the type "nologin" may look like this:
__file /etc/nologin --type file --source "$__type/files/default.nologin"
-
+cdist-tutorial(7)
+
-
+cdist-type(7)
+
Copyright (C) 2010-2012 Nico Schottelius. Free use of this software is
+granted under the terms of the GNU General Public License version 3 (GPLv3).
cdist-quickstart - jump in and enjoy cdist
This tutorial is aimed at people learning cdist and shows
+typical approaches as well as gives an easy start into
+the world of configuration management.
This tutorial assumes you are configuring localhost, because
+it is always available. Just replace localhost with your target
+host for real life usage.
3. QUICK START - GET YOUR HANDS DIRTY NOW
For those who just want to configure a system with the
+cdist configuration management and do not need (or want)
+to understand everything.
Cdist uses ssh for communication and transportation
+and usually logs into the target host as the
+root user. So you need to configure the ssh server
+of the target host to allow root logins: Edit
+the file /etc/ssh/sshd_config and add one of the following
+lines:
# Allow login only via public key
+PermitRootLogin without-password
+
+# Allow login via password and public key
+PermitRootLogin yes
As cdist uses ssh intensively, it is recommended to setup authentication
+with public keys:
# Generate pubkey pair as a normal user
+ssh-keygen
+
+# Copy pubkey over to target host
+ssh-copy-id root@localhost
Have a look at ssh-agent(1) and ssh-add(1) on how to cache the password for
+your public key. Usually it looks like this:
# Start agent and export variables
+eval `ssh-agent`
+
+# Add keys (requires password for every identity file)
+ssh-add
At this point you should be able to ssh root@localhost without
+re-entering the password. If something failed until here, ensure that
+all steps went successfully and you have read and understood the
+documentation.
As soon as you are able to login without password to localhost,
+we can use cdist to configure it. You can copy and paste the following
+code into your shell to get started and configure localhost:
# Get cdist
+git clone git://git.schottelius.org/cdist
+
+# Create manifest (maps configuration to host(s)
+cd cdist
+echo '__file /etc/cdist-configured' > cdist/conf/manifest/init
+
+# Configure localhost in verbose mode
+./bin/cdist config -v localhost
+
+# Find out that cdist created /etc/cdist-configured
+ls -l /etc/cdist-configured
That’s it, you’ve successfully used cdist to configure your first host!
+Continue reading the next sections, to understand what you did and how
+to create a more sophisticated configuration.
-
+cdist(1)
+
-
+cdist-tutorial(7)
+
Copyright (C) 2011-2012 Nico Schottelius. Free use of this software is
+granted under the terms of the GNU General Public License version 3 (GPLv3).
cdist-reference - Variable, path and type reference for cdist
The following global explorers are available:
-
+hostname
+
-
+interfaces
+
-
+lsb_codename
+
-
+lsb_description
+
-
+lsb_id
+
-
+lsb_release
+
-
+machine
+
-
+os
+
-
+os_version
+
-
+runlevel
+
-
+$HOME/.cdist
+
-
+ The standard cdist configuration directory relative to your home directory
+ This is usually the place you want to store your site specific configuration
+
-
+cdist/conf/
+
-
+ The distribution configuration directory
+ This contains types and explorers to be used
+
-
+confdir
+
-
+ Cdist will use all available configuration directories and create
+ a temporary confdir containing links to the real configuration directories.
+ This way it is possible to merge configuration directories.
+ By default it consists of everything in $HOME/.cdist and cdist/conf/.
+ For more details see cdist(1)
+
-
+confdir/manifest/init
+
-
+ This is the central entry point.
+ It is an executable (+x bit set) shell script that can use
+ values from the explorers to decide which configuration to create
+ for the specified target host.
+ Its intent is to used to define mapping from configurations to hosts.
+
-
+confdir/manifest/*
+
-
+ All other files in this directory are not directly used by cdist, but you
+ can seperate configuration mappings, if you have a lot of code in the
+ conf/manifest/init file. This may also be helpful to have different admins
+ maintain different groups of hosts.
+
-
+confdir/explorer/<name>
+
-
+ Contains explorers to be run on the target hosts, see cdist-explorer(7).
+
-
+confdir/type/
+
-
+ Contains all available types, which are used to provide
+ some kind of functionality. See cdist-type(7).
+
-
+confdir/type/<name>/
+
-
+ Home of the type <name>.
+ This directory is referenced by the variable __type (see below).
+
-
+confdir/type/<name>/man.text
+
-
+ Manpage in Asciidoc format (required for inclusion into upstream)
+
-
+confdir/type/<name>/manifest
+
-
+ Used to generate additional objects from a type.
+
-
+confdir/type/<name>/gencode-local
+
-
+ Used to generate code to be executed on the source host
+
-
+confdir/type/<name>/gencode-remote
+
-
+ Used to generate code to be executed on the target host
+
-
+confdir/type/<name>/parameter/required
+
-
+ Parameters required by type, \n seperated list.
+
-
+confdir/type/<name>/parameter/optional
+
-
+ Parameters optionally accepted by type, \n seperated list.
+
-
+confdir/type/<name>/parameter/boolean
+
-
+ Boolean parameters accepted by type, \n seperated list.
+
-
+confdir/type/<name>/explorer
+
-
+ Location of the type specific explorers.
+ This directory is referenced by the variable __type_explorer (see below).
+ See cdist-explorer(7).
+
-
+confdir/type/<name>/files
+
-
+ This directory is reserved for user data and will not be used
+ by cdist at any time
+
-
+out/
+
-
+ This directory contains output of cdist and is usually located
+ in a temporary directory and thus will be removed after the run.
+ This directory is referenced by the variable __global (see below).
+
-
+out/explorer
+
-
+ Output of general explorers.
+
-
+out/object
+
-
+ Objects created for the host.
+
-
+out/object/<object>
+
-
+ Contains all object specific information.
+ This directory is referenced by the variable __object (see below).
+
-
+out/object/<object>/explorers
+
-
+ Output of type specific explorers, per object.
+
The following types are available:
For object to object communication and tests, the following paths are
+usable within a object directory:
-
+changed
+
-
+ This empty file exists in an object directory, if the object has
+ code to be excuted (either remote or local)
+
-
+__explorer
+
-
+ Directory that contains all global explorers.
+ Available for: initial manifest, explorer, type explorer
+
-
+__manifest
+
-
+ Directory that contains the initial manifest.
+ Available for: initial manifest, type manifest
+
-
+__global
+
-
+ Directory that contains generic output like explorer.
+ Available for: initial manifest, type manifest, type gencode
+
-
+__object
+
-
+ Directory that contains the current object.
+ Available for: type manifest, type explorer, type gencode
+
-
+__object_id
+
-
+ The type unique object id.
+ Available for: type manifest, type explorer, type gencode
+ Note: The leading and the trailing "/" will always be stripped (caused by
+ the filesystem database and ensured by the core).
+ Note: Double slashes ("//") will not be fixed and result in an error.
+
-
+__object_name
+
-
+ The full qualified name of the current object.
+ Available for: type manifest, type explorer, type gencode
+
-
+__target_host
+
-
+ The host we are deploying to.
+ Available for: explorer, initial manifest, type explorer, type manifest, type gencode
+
-
+__type
+
-
+ Path to the current type.
+ Available for: type manifest, type gencode
+
-
+__type_explorer
+
-
+ Directory that contains the type explorers.
+ Available for: type explorer
+
Copyright (C) 2011-2012 Nico Schottelius. Free use of this software is
+granted under the terms of the GNU General Public License version 3 (GPLv3).
cdist-remote-exec-copy(7)
cdist-remote-exec-copy - How to use remote exec and copy
Cdist interacts with the target host in two ways:
+- it executes code (remote_exec)
+- and it copies files (remote_copy)
By default this is accomplished with ssh and scp respectively.
+The default implementations used by cdist are:
+remote_exec: ssh -o User=root -q
+remote_copy: scp -o User=root -q
The user can override these defaults by providing custom implementations and
+passing them to cdist with the --remote-exec and/or --remote-copy arguments.
For remote_exec, the custom implementation must behave as if it where ssh.
+For remote_copy, it must behave like scp.
With this simple interface the user can take total control of how cdist
+interacts with the target when required, while the default implementation
+remains as simple as possible.
See cdist/other/examples/remote/ for some example implementations.
Copyright (C) 2011-2012 Nico Schottelius. Free use of this software is
+granted under the terms of the GNU General Public License version 3 (GPLv3).
cdist-stages - Stages used during configuration deployment
Starting the execution of deployment with cdist, cdist passes
+through different stages.
3. 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.
4. 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, if it has different parameters.
5. STAGE 3: OBJECT INFORMATION RETRIEVAL
Every object is checked whether its type has explorers and if so, these are
+executed on the target host. The results are transferred back
+and can be used in the following stages to decide what changes need to be made
+on the target to implement the desired state.
6. STAGE 4: RUN THE OBJECT MANIFEST
Every object is checked whether its type has a executable manifest. 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.example.org 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.
7. STAGE 5: CODE GENERATION
In this stage for every created object its type is checked for executable
+gencode scripts. The gencode scripts generate the code to be executed on the
+target on stdout. If the gencode executables fail, they must print diagnostic
+messages on stderr and exit non-zero.
8. 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.
The cache stores the information from the current run for later use.
If, and only if, all the stages complete without an errors, the configuration
+will be applied to the target.
-
+cdist(1)
+
-
+cdist-reference(7)
+
Copyright (C) 2010-2012 Nico Schottelius, Steven Armstrong. Free use of this software is
+granted under the terms of the GNU General Public License version 3 (GPLv3).
cdist-tutorial - a guided introduction into cdist
This document gives you a pointer on what to read in
+which order and is thus a "guide to the right locations".
+So in case you are just starting, just "begin at the beginning"
+(Brave New World). You can see the target audience in [] brackets
+after the description.
-
+cdist-quickstart
+
-
+ New to cdist? Want to get your hands dirty? Read this. [beginner]
+
-
+cdist-bootstrap
+
-
+ The comprehensive guide to your first cdist installation [beginner]
+
-
+cdist-manifest
+
-
+ Learn how to define which hosts get which configurations [beginner]
+
-
+cdist-type
+
-
+ Understand how types are working and created [intermediate]
+
-
+cdist-best-practice
+
-
+ Hints from real life experience to help you to organise cdist [intermediate]
+
-
+cdist-reference
+
-
+ The type, explorers and environment variables reference [intermediate]
+
-
+cdist-explorer
+
-
+ Interested in getting more information about the target system? [intermediate]
+
-
+cdist-stages
+
-
+ Understand the internal workflow of cdist. [advanced]
+
-
+cdist-hacker
+
-
+ README, if you want to extend or modify cdist. [hacker]
+
-
+cdist(1)
+
-
+cdist-type(7)
+
-
+cdist-best-practice(7)
+
-
+cdist-stages(7)
+
-
+Brave New World by Aldous Huxley
+
Copyright (C) 2011-2012 Nico Schottelius. Free use of this software is
+granted under the terms of the GNU General Public License version 3 (GPLv3).