forked from ungleich-public/cdist
Restructure and fix and improve docs and manpages.
This commit is contained in:
Darko Poljak
parent
a220d4805a
commit
51c94e9e82
125 changed files with 1799 additions and 816 deletions
|
|
@ -1,241 +0,0 @@
|
|||
cdist-best-practice(7)
|
||||
======================
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-best-practice - Practices used in real environments
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
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).
|
||||
|
||||
|
||||
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
|
||||
|
||||
|
||||
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
|
||||
|
||||
|
||||
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
|
||||
|
||||
|
||||
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"
|
||||
|
||||
|
||||
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 across 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
|
||||
|
||||
|
||||
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)
|
||||
|
||||
|
||||
TEMPLATING
|
||||
----------
|
||||
* 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
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
#!/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:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# export variables needed for the template
|
||||
export SERVERNAME='test"
|
||||
export ROOT='/var/www/test'
|
||||
# render the template
|
||||
mkdir -p "$__object/files"
|
||||
"$__type/files/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"
|
||||
|
||||
|
||||
TESTING A NEW TYPE
|
||||
------------------
|
||||
If you want to test a new type on a node, you can tell cdist to only use an
|
||||
object of this type: Use the '--initial-manifest' parameter
|
||||
with - (stdin) as argument and feed object into stdin
|
||||
of cdist:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
# Singleton type without parameter
|
||||
echo __ungleich_munin_server | cdist --initial-manifest - munin.panter.ch
|
||||
|
||||
# Singleton type with parameter
|
||||
echo __ungleich_munin_node --allow 1.2.3.4 | \
|
||||
cdist --initial-manifest - rails-19.panter.ch
|
||||
|
||||
# Normal type
|
||||
echo __file /tmp/stdintest --mode 0644 | \
|
||||
cdist --initial-manifest - cdist-dev-01.ungleich.ch
|
||||
|
||||
|
||||
OTHER CONTENT IN CDIST REPOSITORY
|
||||
---------------------------------
|
||||
Usually the cdist repository contains all configuration
|
||||
items. Sometimes you may have additional resources that
|
||||
you would like to store in your central configuration
|
||||
repositiory (like password files from KeepassX,
|
||||
Libreoffice diagrams, etc.).
|
||||
|
||||
It is recommended to use a subfolder named "non-cdist"
|
||||
in the repository for such content: It allows you to
|
||||
easily distinguish what is used by cdist and what not
|
||||
and also to store all important files in one
|
||||
repository.
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist(1) <../man1/cdist.html>`_
|
||||
- `cdist-tutorial(7) <cdist-tutorial.html>`_
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
Copyright \(C) 2011-2013 Nico Schottelius. Free use of this software is
|
||||
granted under the terms of the GNU General Public License version 3 (GPLv3).
|
||||
|
|
@ -1,140 +0,0 @@
|
|||
cdist-bootstrap(7)
|
||||
==================
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-bootstrap - Setup cdist environment
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
INTRODUCTION
|
||||
------------
|
||||
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.
|
||||
|
||||
|
||||
LOCATION
|
||||
---------
|
||||
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 on is recommended, for use as backup as well as to allow easy collaboration
|
||||
with others.
|
||||
|
||||
For more sophisticated setups developing cdist configurations with multiple
|
||||
people, have a look at cdist-best-practice(7).
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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**.
|
||||
|
||||
|
||||
UPDATING FROM ORIGIN
|
||||
--------------------
|
||||
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
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist(1) <../man1/cdist.html>`_
|
||||
- `cdist-tutorial(7) <cdist-tutorial.html>`_
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
Copyright \(C) 2012 Nico Schottelius. Free use of this software is
|
||||
granted under the terms of the GNU General Public License version 3 (GPLv3).
|
||||
|
|
@ -1,74 +0,0 @@
|
|||
cdist-explorer(7)
|
||||
=================
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-explorer - Explore the target systems
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
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.
|
||||
|
||||
EXAMPLES
|
||||
--------
|
||||
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:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
if [ -f "$__object/parameter/name" ]; then
|
||||
name="$(cat "$__object/parameter/name")"
|
||||
else
|
||||
name="$__object_id"
|
||||
fi
|
||||
|
||||
# Expect dpkg failing, if package is not known / installed
|
||||
dpkg -s "$name" 2>/dev/null || exit 0
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist(1) <../man1/cdist.html>`_
|
||||
- `cdist-reference(7) <cdist-reference.html>`_
|
||||
- `cdist-stages(7) <cdist-stages.html>`_
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
Copyright \(C) 2010-2014 Nico Schottelius. Free use of this software is
|
||||
granted under the terms of the GNU General Public License version 3 (GPLv3).
|
||||
|
|
@ -1,161 +0,0 @@
|
|||
cdist-hacker(7)
|
||||
===============
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-hacker - How to get (stuff) into cdist
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
WELCOME
|
||||
-------
|
||||
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.
|
||||
|
||||
|
||||
REPORTING BUGS
|
||||
--------------
|
||||
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.
|
||||
|
||||
|
||||
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).
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
EXAMPLE GIT WORKFLOW
|
||||
---------------------
|
||||
The following workflow works fine for most developers::
|
||||
|
||||
# get latest upstream master branch
|
||||
git clone https://github.com/telmich/cdist.git
|
||||
|
||||
# update if already existing
|
||||
cd cdist; git fetch -v; git merge origin/master
|
||||
|
||||
# create a new branch for your feature/bugfix
|
||||
cd cdist # if you haven't done before
|
||||
git checkout -b documentation_cleanup
|
||||
|
||||
# *hack*
|
||||
*hack*
|
||||
|
||||
# clone the cdist repository on github if you haven't done so
|
||||
|
||||
# configure your repo to know about your clone (only once)
|
||||
git remote add github git@github.com:YOURUSERNAME/cdist.git
|
||||
|
||||
# push the new branch to github
|
||||
git push github documentation_cleanup
|
||||
|
||||
# (or everything)
|
||||
git push --mirror github
|
||||
|
||||
# create a pull request at github (use a browser)
|
||||
# *fixthingsbecausequalityassurancefoundissuesinourpatch*
|
||||
*hack*
|
||||
|
||||
# push code to github again
|
||||
git push ... # like above
|
||||
|
||||
# add comment that everything should be green now (use a browser)
|
||||
|
||||
# go back to master branch
|
||||
git checkout master
|
||||
|
||||
# update master branch that includes your changes now
|
||||
git fetch -v origin
|
||||
git diff master..origin/master
|
||||
git merge origin/master
|
||||
|
||||
If at any point you want to go back to the original master branch, you can
|
||||
use **git stash** to stash your changes away::
|
||||
|
||||
# assume you are on documentation_cleanup
|
||||
git stash
|
||||
|
||||
# change to master and update to most recent upstream version
|
||||
git checkout master
|
||||
git fetch -v origin
|
||||
git merge origin/master
|
||||
|
||||
Similar when you want to develop another new feature, you go back
|
||||
to the master branch and create another branch based on it::
|
||||
|
||||
# change to master and update to most recent upstream version
|
||||
git checkout master
|
||||
git fetch -v origin
|
||||
git merge origin/master
|
||||
|
||||
git checkout -b another_feature
|
||||
|
||||
(you can repeat the code above for as many features as you want to develop
|
||||
in parallel)
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist(1) <../man1/cdist.html>`_
|
||||
- git(1)
|
||||
- git-checkout(1)
|
||||
- git-stash(1)
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
Copyright \(C) 2011-2013 Nico Schottelius. Free use of this software is
|
||||
granted under the terms of the GNU General Public License version 3 (GPLv3).
|
||||
|
|
@ -1,274 +0,0 @@
|
|||
cdist-manifest(7)
|
||||
=================
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-manifest - (Re-)Use types
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
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 = absent
|
||||
__package apache2 --state absent
|
||||
|
||||
# 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.
|
||||
|
||||
|
||||
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).
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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
|
||||
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 separated.
|
||||
|
||||
::
|
||||
|
||||
1 # No dependency
|
||||
2 __file /etc/cdist-configured
|
||||
3
|
||||
4 # Require above object
|
||||
5 require="__file/etc/cdist-configured" __link /tmp/cdist-testfile \
|
||||
6 --source /etc/cdist-configured --type symbolic
|
||||
7
|
||||
8 # Require two objects
|
||||
9 require="__file/etc/cdist-configured __link/tmp/cdist-testfile" \
|
||||
10 __file /tmp/cdist-another-testfile
|
||||
|
||||
|
||||
Above the "require" variable is only set for the command that is
|
||||
immediately following it. Dependencies should always be declared that way.
|
||||
|
||||
On line 4 you can see that the instantion of a type "\__link" object needs
|
||||
the object "__file/etc/cdist-configured" to be present, before it can proceed.
|
||||
|
||||
This also means that the "\__link" command must make sure, that either
|
||||
"\__file/etc/cdist-configured" allready is present, or, if it's not, it needs
|
||||
to be created. The task of cdist is to make sure, that the dependency will be
|
||||
resolved appropriately and thus "\__file/etc/cdist-configured" be created
|
||||
if necessary before "__link" proceeds (or to abort execution with an error).
|
||||
|
||||
If you really need to make all types depend on a common dependency, you can
|
||||
export the "require" variable as well. But then, if you need to add extra
|
||||
dependencies to a specific type, you have to make sure that you append these
|
||||
to the globally already defined one.
|
||||
|
||||
::
|
||||
|
||||
# First of all, update the package index
|
||||
__package_update_index
|
||||
# Upgrade all the installed packages afterwards
|
||||
require="__package_update_index" __package_upgrade_all
|
||||
# Create a common dependency for all the next types so that they get to
|
||||
# be executed only after the package upgrade has finished
|
||||
export require="__package_upgrade_all"
|
||||
|
||||
# Ensure that lighttpd is installed after we have upgraded all the packages
|
||||
__package lighttpd --state present
|
||||
# Ensure that munin is installed after lighttpd is present and after all
|
||||
# the packages are upgraded
|
||||
require="$require __package/lighttpd" __package munin --state present
|
||||
|
||||
|
||||
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.
|
||||
|
||||
You can find an more in depth description of the flow execution of manifests
|
||||
in cdist-stages(7) and of how types work in cdist-type(7).
|
||||
|
||||
|
||||
CREATE DEPENDENCIES FROM EXECUTION ORDER
|
||||
-----------------------------------------
|
||||
You can tell cdist to execute all types in the order in which they are created
|
||||
in the manifest by setting up the variable CDIST_ORDER_DEPENDENCY.
|
||||
When cdist sees that this variable is setup, the current created object
|
||||
automatically depends on the previously created object.
|
||||
|
||||
It essentially helps you to build up blocks of code that build upon each other
|
||||
(like first creating the directory xyz than the file below the directory).
|
||||
|
||||
|
||||
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 wish, you can setup the environment variable CDIST_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 encounters the affected objects, otherwise this results
|
||||
in an undefined situation.
|
||||
|
||||
If CDIST_OVERRIDE and CDIST_ORDER_DEPENDENCY are set for an object,
|
||||
CDIST_ORDER_DEPENDENCY will be ignored, because adding a dependency in case of
|
||||
overrides would result in circular dependencies, which is an error.
|
||||
|
||||
|
||||
EXAMPLES
|
||||
--------
|
||||
The initial manifest may for instance contain the following code:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
# Always create this file, so other sysadmins know cdist is used.
|
||||
__file /etc/cdist-configured
|
||||
|
||||
case "$__target_host" in
|
||||
my.server.name)
|
||||
__directory /root/bin/
|
||||
__file /etc/issue.net --source "$__manifest/issue.net
|
||||
;;
|
||||
esac
|
||||
|
||||
The manifest of the type "nologin" may look like this:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
__file /etc/nologin --source "$__type/files/default.nologin"
|
||||
|
||||
This example makes use of dependencies:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
# Ensure that lighttpd is installed
|
||||
__package lighttpd --state present
|
||||
# Ensure that munin makes use of lighttpd instead of the default webserver
|
||||
# package as decided by the package manager
|
||||
require="__package/lighttpd" __package munin --state present
|
||||
|
||||
How to override objects:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
# for example in the inital manifest
|
||||
|
||||
# create 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 conditionally 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_OVERRIDE=yes __user foobar --password 'some_other_hash'
|
||||
# it's only an override, means the parameter --home is not touched
|
||||
# and stays at the original value of /home/foobarexample
|
||||
|
||||
Dependencies defined by execution order work as following:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
# Tells cdist to execute all types in the order in which they are created ...
|
||||
export CDIST_ORDER_DEPENDENCY=on
|
||||
__sample_type 1
|
||||
require="__some_type_somewhere/id" __sample_type 2
|
||||
__example_type 23
|
||||
# Now this types are executed in the creation order until the variable is unset
|
||||
unset CDIST_ORDER_DEPENDENCY
|
||||
# all now following types cdist makes the order ..
|
||||
__not_in_order_type 42
|
||||
|
||||
# how it works :
|
||||
# this lines above are translated to:
|
||||
__sample_type 1
|
||||
require="__some_type_somewhere/id __sample_type/1" __sample_type 2
|
||||
require="__sample_type/2" __example_type 23
|
||||
__not_in_order_type 42
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist-tutorial(7) <cdist-tutorial.html>`_
|
||||
- `cdist-type(7) <cdist-type.html>`_
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
Copyright \(C) 2010-2014 Nico Schottelius. Free use of this software is
|
||||
granted under the terms of the GNU General Public License version 3 (GPLv3).
|
||||
|
|
@ -1,114 +0,0 @@
|
|||
cdist-messaging(7)
|
||||
==================
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-messaging - How the initial manifest and types can communication
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
cdist has a simple but powerful way of allowing communication between
|
||||
the initial manifest and types as well as types and types.
|
||||
|
||||
Whenever execution is passed from cdist to one of the
|
||||
scripts described below, cdist generate 2 new temporary files
|
||||
and exports the environment variables **__messages_in** and
|
||||
**__messages_out** to point to them.
|
||||
|
||||
Before handing over the control, the content of the global message
|
||||
file is copied into the file referenced by **$__messages_in**.
|
||||
|
||||
After cdist gained control back, the content of the file referenced
|
||||
by **$__messages_out** is appended to the global message file.
|
||||
|
||||
This way overwriting any of the two files by accident does not
|
||||
interfere with other types.
|
||||
|
||||
The order of execution is not defined unless you create dependencies
|
||||
between the different objects (see cdist-manifest(7)) and thus you
|
||||
can only react reliably on messages by objects that you depend on.
|
||||
|
||||
|
||||
AVAILABILITY
|
||||
------------
|
||||
Messaging is possible between all **local** scripts:
|
||||
|
||||
- initial manifest
|
||||
- type/manifest
|
||||
- type/gencode-local
|
||||
- type/gencode-remote
|
||||
|
||||
|
||||
EXAMPLES
|
||||
--------
|
||||
When you want to emit a message use:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
echo "something" >> "$__messages_out"
|
||||
|
||||
When you want to react on a message use:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
if grep -q "^__your_type/object/id:something" "$__messages_in"; then
|
||||
echo "I do something else"
|
||||
fi
|
||||
|
||||
Some real life examples:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
# Reacting on changes from block for keepalive
|
||||
if grep -q "^__block/keepalive-vrrp" "$__messages_in"; then
|
||||
echo /etc/init.d/keepalived restart
|
||||
fi
|
||||
|
||||
# Reacting on changes of configuration files
|
||||
if grep -q "^__file/etc/one" $__messages_in; then
|
||||
echo 'for init in /etc/init.d/opennebula*; do $init restart; done'
|
||||
fi
|
||||
|
||||
Restart sshd on changes
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
os="$(cat "$__global/explorer/os")"
|
||||
|
||||
case "$os" in
|
||||
centos|redhat|suse)
|
||||
restart="/etc/init.d/sshd restart"
|
||||
;;
|
||||
debian|ubuntu)
|
||||
restart="/etc/init.d/ssh restart"
|
||||
;;
|
||||
*)
|
||||
cat << eof >&2
|
||||
Unsupported os $os.
|
||||
If you would like to have this type running on $os,
|
||||
you can either develop the changes and send a pull
|
||||
request or ask for a quote at www.ungleich.ch
|
||||
eof
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
|
||||
if grep -q "^__key_value/PermitRootLogin" "$__messages_in"; then
|
||||
echo $restart
|
||||
fi
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist(1) <../man1/cdist.html>`_
|
||||
- `cdist-manifest(7) <cdist-manifest.html>`_
|
||||
- `cdist-reference(7) <cdist-reference.html>`_
|
||||
- `cdist-type(7) <cdist-type.html>`_
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
Copyright \(C) 2013 Nico Schottelius. Free use of this software is
|
||||
granted under the terms of the GNU General Public License version 3 (GPLv3).
|
||||
|
|
@ -1,98 +0,0 @@
|
|||
cdist-quickstart(7)
|
||||
===================
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-quickstart - Jump in and enjoy cdist
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
INTRODUCTION
|
||||
------------
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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
|
||||
# Mirrors can be found on
|
||||
# http://www.nico.schottelius.org/software/cdist/install/#index2h4
|
||||
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.
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist(1) <../man1/cdist.html>`_
|
||||
- `cdist-tutorial(7) <cdist-tutorial.html>`_
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
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).
|
||||
|
|
@ -1,48 +0,0 @@
|
|||
cdist-remote-exec-copy(7)
|
||||
=========================
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-remote-exec-copy - How to use remote exec and copy
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
INTRO
|
||||
-----
|
||||
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.
|
||||
|
||||
|
||||
EXAMPLES
|
||||
--------
|
||||
See cdist/other/examples/remote/ for some example implementations.
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist(1) <../man1/cdist.html>`_
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
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).
|
||||
|
|
@ -1,89 +0,0 @@
|
|||
cdist-stages(7)
|
||||
===============
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-stages - Stages used during configuration deployment
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
Starting the execution of deployment with cdist, cdist passes
|
||||
through different stages.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
STAGE 7: CACHE
|
||||
--------------
|
||||
The cache stores the information from the current run for later use.
|
||||
|
||||
|
||||
SUMMARY
|
||||
-------
|
||||
If, and only if, all the stages complete without an errors, the configuration
|
||||
will be applied to the target.
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist(1) <../man1/cdist.html>`_
|
||||
- `cdist-reference(7) <cdist-reference.html>`_
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
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).
|
||||
|
|
@ -1,64 +0,0 @@
|
|||
cdist-troubleshooting(7)
|
||||
========================
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-troubleshooting - Common problems and their solutions
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
ERROR IN MANIFEST IS NOT CONSIDERED AN ERROR BY CDIST
|
||||
-----------------------------------------------------
|
||||
Situation: You are executing other scripts from a manifest.
|
||||
This script fails, but cdist does not recognise the error.
|
||||
An example script would be something like this:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
% cat ~/.cdist/manifest/init
|
||||
"$__manifest/special"
|
||||
% cat ~/.cdist/manifest/special
|
||||
#!/bin/sh
|
||||
echo "Here is an unclean exiting script"
|
||||
somecommandthatdoesnotexist
|
||||
echo "I continue here although previous command failed"
|
||||
|
||||
We can clearly see that **somecommandthatdoesnotexist**
|
||||
will fail in ~/.cdist/manifest/special. But as the custom
|
||||
script is not called with the -e flag (exit on failure) of shell,
|
||||
it does not lead to an error. And thus cdist sees the exit 0
|
||||
code of the last echo line instead of the failing command.
|
||||
|
||||
All scripts executed by cdist carry the -e flag.
|
||||
To prevent the above from happening, there are three solutions available,
|
||||
two of which can be used in the calling script:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
# Execute as before, but abort on failure
|
||||
sh -e "$__manifest/special"
|
||||
|
||||
# Source the script in our namespace, runs in a set -e environment:
|
||||
. "$__manifest/special"
|
||||
|
||||
The third solution is to include a shebang header in every script
|
||||
you write to use the -e flag:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
% cat ~/.cdist/manifest/special
|
||||
#!/bin/sh -e
|
||||
...
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist(1) <../man1/cdist.html>`_
|
||||
- `cdist-tutorial(7) <cdist-tutorial.html>`_
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
Copyright \(C) 2013 Nico Schottelius. Free use of this software is
|
||||
granted under the terms of the GNU General Public License version 3 (GPLv3).
|
||||
|
|
@ -1,58 +0,0 @@
|
|||
cdist-tutorial(7)
|
||||
=================
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-tutorial - A guided introduction into cdist
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
INTRODUCTION
|
||||
------------
|
||||
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]
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist(1) <../man1/cdist.html>`_
|
||||
- `cdist-type(7) <cdist-type.html>`_
|
||||
- `cdist-best-practice(7) <cdist-best-practice.html>`_
|
||||
- `cdist-stages(7) <cdist-stages.html>`_
|
||||
- Brave New World by Aldous Huxley
|
||||
|
||||
COPYING
|
||||
-------
|
||||
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).
|
||||
|
|
@ -1,317 +0,0 @@
|
|||
cdist-type(7)
|
||||
=============
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-type - Functionality bundled
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
|
||||
::
|
||||
|
||||
__TYPE ID --parameter value [--parameter value ...]
|
||||
__TYPE --parameter value [--parameter value ...] (for singletons)
|
||||
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
Types are the main component of cdist and define functionality. If you
|
||||
use cdist, you'll write a type for every functionality you would like
|
||||
to use.
|
||||
|
||||
|
||||
HOW TO USE A TYPE
|
||||
-----------------
|
||||
You can use types from the initial manifest or the type manifest like a
|
||||
normal shell command:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
# Creates empty file /etc/cdist-configured
|
||||
__file /etc/cdist-configured --type file
|
||||
|
||||
# Ensure tree is installed
|
||||
__package tree --state installed
|
||||
|
||||
A list of supported types can be found in the cdist-reference(7) manpage.
|
||||
|
||||
|
||||
SINGLETON TYPES
|
||||
---------------
|
||||
If a type is flagged as a singleton, it may be used only
|
||||
once per host. This is useful for types which can be used only once on a
|
||||
system. Singleton types do not take an object name as argument.
|
||||
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
# __issue type manages /etc/issue
|
||||
__issue
|
||||
|
||||
# Probably your own type - singletons may use parameters
|
||||
__myfancysingleton --colour green
|
||||
|
||||
|
||||
HOW TO WRITE A NEW TYPE
|
||||
-----------------------
|
||||
A type consists of
|
||||
|
||||
- parameter (optional)
|
||||
- manifest (optional)
|
||||
- singleton (optional)
|
||||
- explorer (optional)
|
||||
- gencode (optional)
|
||||
|
||||
Types are stored below cdist/conf/type/. Their name should always be prefixed with
|
||||
two underscores (__) to prevent collisions with other executables in $PATH.
|
||||
|
||||
To implement a new type, create the directory **cdist/conf/type/__NAME**.
|
||||
|
||||
|
||||
DEFINING PARAMETERS
|
||||
-------------------
|
||||
Every type consists of required, optional and boolean parameters, which must
|
||||
each be declared in a newline separated file in **parameter/required**,
|
||||
**parameter/required_multiple**, **parameter/optional**,
|
||||
**parameter/optional_multiple** and **parameter/boolean**.
|
||||
Parameters which are allowed multiple times should be listed in
|
||||
required_multiple or optional_multiple respectively. All other parameters
|
||||
follow the standard unix behaviour "the last given wins".
|
||||
If either is missing, the type will have no required, no optional, no boolean
|
||||
or no parameters at all.
|
||||
|
||||
Default values for optional parameters can be predefined in
|
||||
**parameter/default/<name>**.
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
echo servername >> cdist/conf/type/__nginx_vhost/parameter/required
|
||||
echo logdirectory >> cdist/conf/type/__nginx_vhost/parameter/optional
|
||||
echo loglevel >> cdist/conf/type/__nginx_vhost/parameter/optional
|
||||
mkdir cdist/conf/type/__nginx_vhost/parameter/default
|
||||
echo warning > cdist/conf/type/__nginx_vhost/parameter/default/loglevel
|
||||
echo server_alias >> cdist/conf/type/__nginx_vhost/parameter/optional_multiple
|
||||
echo use_ssl >> cdist/conf/type/__nginx_vhost/parameter/boolean
|
||||
|
||||
|
||||
USING PARAMETERS
|
||||
----------------
|
||||
The parameters given to a type can be accessed and used in all type scripts
|
||||
(e.g manifest, gencode, explorer). Note that boolean parameters are
|
||||
represented by file existence. File exists -> True,
|
||||
file does not exist -> False
|
||||
|
||||
Example: (e.g. in cdist/conf/type/__nginx_vhost/manifest)
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
# required parameter
|
||||
servername="$(cat "$__object/parameter/servername")"
|
||||
|
||||
# optional parameter
|
||||
if [ -f "$__object/parameter/logdirectory" ]; then
|
||||
logdirectory="$(cat "$__object/parameter/logdirectory")"
|
||||
fi
|
||||
|
||||
# optional parameter with predefined default
|
||||
loglevel="$(cat "$__object/parameter/loglevel")"
|
||||
|
||||
# boolean parameter
|
||||
if [ -f "$__object/parameter/use_ssl" ]; then
|
||||
# file exists -> True
|
||||
# do some fancy ssl stuff
|
||||
fi
|
||||
|
||||
# parameter with multiple values
|
||||
if [ -f "$__object/parameter/server_alias" ]; then
|
||||
for alias in $(cat "$__object/parameter/server_alias"); do
|
||||
echo $alias > /some/where/usefull
|
||||
done
|
||||
fi
|
||||
|
||||
|
||||
INPUT FROM STDIN
|
||||
----------------
|
||||
Every type can access what has been written on stdin when it has been called.
|
||||
The result is saved into the **stdin** file in the object directory.
|
||||
|
||||
Example use of a type: (e.g. in cdist/conf/type/__archlinux_hostname)
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
__file /etc/rc.conf --source - << eof
|
||||
...
|
||||
HOSTNAME="$__target_host"
|
||||
...
|
||||
eof
|
||||
|
||||
If you have not seen this syntax (<< eof) before, it may help you to read
|
||||
about "here documents".
|
||||
|
||||
In the __file type, stdin is used as source for the file, if - is used for source:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
if [ -f "$__object/parameter/source" ]; then
|
||||
source="$(cat "$__object/parameter/source")"
|
||||
if [ "$source" = "-" ]; then
|
||||
source="$__object/stdin"
|
||||
fi
|
||||
....
|
||||
|
||||
|
||||
WRITING THE MANIFEST
|
||||
--------------------
|
||||
In the manifest of a type you can use other types, so your type extends
|
||||
their functionality. A good example is the __package type, which in
|
||||
a shortened version looks like this:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
os="$(cat "$__global/explorer/os")"
|
||||
case "$os" in
|
||||
archlinux) type="pacman" ;;
|
||||
debian|ubuntu) type="apt" ;;
|
||||
gentoo) type="emerge" ;;
|
||||
*)
|
||||
echo "Don't know how to manage packages on: $os" >&2
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
|
||||
__package_$type "$@"
|
||||
|
||||
As you can see, the type can reference different environment variables,
|
||||
which are documented in cdist-reference(7).
|
||||
|
||||
Always ensure the manifest is executable, otherwise cdist will not be able
|
||||
to execute it. For more information about manifests see cdist-manifest(7).
|
||||
|
||||
|
||||
SINGLETON - ONE INSTANCE ONLY
|
||||
-----------------------------
|
||||
If you want to ensure that a type can only be used once per target, you can
|
||||
mark it as a singleton: Just create the (empty) file "singleton" in your type
|
||||
directory:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
touch cdist/conf/type/__NAME/singleton
|
||||
|
||||
This will also change the way your type must be called:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
__YOURTYPE --parameter value
|
||||
|
||||
As you can see, the object ID is omitted, because it does not make any sense,
|
||||
if your type can be used only once.
|
||||
|
||||
|
||||
THE TYPE EXPLORERS
|
||||
------------------
|
||||
If a type needs to explore specific details, it can provide type specific
|
||||
explorers, which will be executed on the target for every created object.
|
||||
|
||||
The explorers are stored under the "explorer" directory below the type.
|
||||
It could for instance contain code to check the md5sum of a file on the
|
||||
client, like this (shortened version from the type __file):
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
if [ -f "$__object/parameter/destination" ]; then
|
||||
destination="$(cat "$__object/parameter/destination")"
|
||||
else
|
||||
destination="/$__object_id"
|
||||
fi
|
||||
|
||||
if [ -e "$destination" ]; then
|
||||
md5sum < "$destination"
|
||||
fi
|
||||
|
||||
|
||||
WRITING THE GENCODE SCRIPT
|
||||
--------------------------
|
||||
There are two gencode scripts: **gencode-local** and **gencode-remote**.
|
||||
The output of gencode-local is executed locally, whereas
|
||||
the output of gencode-remote is executed on the target.
|
||||
The gencode scripts can make use of the parameters, the global explorers
|
||||
and the type specific explorers.
|
||||
|
||||
If the gencode scripts encounters an error, it should print diagnostic
|
||||
messages to stderr and exit non-zero. If you need to debug the gencode
|
||||
script, you can write to stderr:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
# Debug output to stderr
|
||||
echo "My fancy debug line" >&2
|
||||
|
||||
# Output to be saved by cdist for execution on the target
|
||||
echo "touch /etc/cdist-configured"
|
||||
|
||||
|
||||
VARIABLE ACCESS FROM THE GENERATED SCRIPTS
|
||||
------------------------------------------
|
||||
In the generated scripts, you have access to the following cdist variables
|
||||
|
||||
- __object
|
||||
- __object_id
|
||||
|
||||
but only for read operations, means there is no back copy of this
|
||||
files after the script execution.
|
||||
|
||||
So when you generate a script with the following content, it will work:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
if [ -f "$__object/parameter/name" ]; then
|
||||
name="$(cat "$__object/parameter/name")"
|
||||
else
|
||||
name="$__object_id"
|
||||
fi
|
||||
|
||||
|
||||
HINTS FOR TYPEWRITERS
|
||||
----------------------
|
||||
It must be assumed that the target is pretty dumb and thus does not have high
|
||||
level tools like ruby installed. If a type requires specific tools to be present
|
||||
on the target, there must be another type that provides this tool and the first
|
||||
type should create an object of the specific type.
|
||||
|
||||
If your type wants to save temporary data, that may be used by other types
|
||||
later on (for instance \__file), you can save them in the subdirectory
|
||||
"files" below $__object (but you must create it yourself).
|
||||
cdist will not touch this directory.
|
||||
|
||||
If your type contains static files, it's also recommended to place them in
|
||||
a folder named "files" within the type (again, because cdist guarantees to
|
||||
never ever touch this folder).
|
||||
|
||||
|
||||
HOW TO INCLUDE A TYPE INTO UPSTREAM CDIST
|
||||
-----------------------------------------
|
||||
If you think your type may be useful for others, ensure it works with the
|
||||
current master branch of cdist and have a look at cdist-hacker(7) on
|
||||
how to submit it.
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist-explorer(7) <cdist-explorer.html>`_
|
||||
- `cdist-hacker(7) <cdist-hacker.html>`_
|
||||
- `cdist-stages(7) <cdist-stages.html>`_
|
||||
- `cdist-tutorial(7) <cdist-tutorial.html>`_
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
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).
|
||||
Loading…
Add table
Add a link
Reference in a new issue