cdist update

This commit is contained in:
Nico Schottelius 2012-11-15 14:26:48 +01:00
parent f24a0848ca
commit fbb237354b
64 changed files with 3118 additions and 21 deletions

View file

@ -2,32 +2,19 @@
![cdist-logo](cdist-logo.png "cdist logo")
the KISS principle and is being used in small up to enterprise grade
environments.
cdist is a usable configuration management system.
It adheres to the KISS principle and
is being used in small up to enterprise grade environments.
cdist is an alternative to other configuration management systems like
[cfengine](http://www.cfengine.org/),
[bcfg2](http://trac.mcs.anl.gov/projects/bcfg2),
[chef](http://wiki.opscode.com/display/chef/)
[cfengine](http://www.cfengine.org/),
and [puppet](http://www.puppetlabs.com/).
* Browse the **documentation** for the [latest version](man/latest) or [all versions (>= 2.0.4)](man)
* Read how to [[install or update cdist|install-update]]
* [[Documentation|documentation]]
* [[Supported Operating Systems|os]]
* [[Installation|install]]
* [[Update|update]]
* [[Support|support]]
### OS support
cdist was tested or is know to run on at least
* [Archlinux](http://www.archlinux.org/)
* [Debian](http://www.debian.org/)
* [CentOS](http://www.centos.org/)
* [Fedora](http://fedoraproject.org/)
* [FreeBSD](http://www.freebsd.org)
* [Gentoo](http://www.gentoo.org/)
* [Mac OS X](http://www.apple.com/macosx/)
* [OpenBSD](http://www.openbsd.org)
* [Redhat](http://www.redhat.com/)
* [Ubuntu](http://www.ubuntu.com/)
* [XenServer](http://www.citrix.com/xenserver/)
[[!tag cdist unix]]

View file

@ -0,0 +1,7 @@
[[!meta title="Documentation"]]
You can browse the latest
[latest version of the manpages](man/latest) or
have a look at [all versions](man).
[[!tag cdist unix]]

176
software/cdist/install.mdwn Normal file
View file

@ -0,0 +1,176 @@
[[!meta title="How to install cdist"]]
[[!toc levels=3]]
## Requirements
### Source Host
This is the machine you use to configure the target hosts.
* /bin/sh: A posix like shell (for instance bash, dash, zsh)
* Python >= 3.2
* SSH client
* Asciidoc (for building the manpages)
### Target Hosts
* /bin/sh: A posix like shell (for instance bash, dash, zsh)
* SSH server
## Requirement Installation: Python >= 3.2
Ensure you have at least Python 3.2 or newer installed on
the **source host**.
You can check this by running **python -V**:
% python -V
Python 3.3.0
### Archlinux
Archlinux includes a recent python in the extra repository.
You can install it using
pacman -S python
### CentOS
See the "From source" section
### Debian
For Debian **wheezy** or newer:
aptitude install python3
On **squeeze** you can add following line in **/etc/apt/sources.list**
deb http://ftp.debian.org/debian wheezy main
And add pinning entry in **/etc/apt/preferences.d/wheezy**:
Package: *
Pin: release n=wheezy
Pin-Priority: 1
Please be aware that both **openssh-server** and **openssh-client** might be
removed on **python3.2** installation. You surely want to reinstall them:
apt-get install -t wheezy openssh-server openssh-client
For older Debian versions, installing python 3.2 from source is required.
### Fedora
Fedora 15 and newer includes a recent python.
You can install it using
yum install python3
### FreeBSD
For the port:
cd /usr/ports/lang/python32/ && make install clean
For the package:
pkg_add -r python32
You can also use any newer version, but at least python 3.2 is required.
### Gentoo
Gentoo only provides python 3.2 in testing packages (http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=3&chap=3).
If you want to ensure nothing breaks you must set back the python version to what was default before.
emerge -av =python-3.2.2 --autounmask-write
emerge -av =python-3.2.2
eselect python list
eselect python list set python3.2
### Max OS X
You can choose between Homebrew and Macports, either way works:
[Homebrew](http://mxcl.github.com/homebrew/) variant:
brew install python3
[Macports](http://www.macports.org/install.php) variant:
port install python32
ln -s /opt/local/bin/python3.2 /opt/local/bin/python3
### Redhat
See the "From source" section
### From Source
For those operating systems not yet supporting Python 3.2:
pyversion=3.2.3
wget http://www.python.org/ftp/python/$pyversion/Python-${pyversion}.tar.bz2
tar xvfj Python-${pyversion}.tar.bz2
cd Python-${pyversion}
./configure
make
sudo make install
This installs python 3.2 to /usr/local/bin.
Ensure this directory is in your PATH environment variable.
## Install cdist
You can install cdist either from git or as a python package.
### From git
Cloning cdist from git gives you the advantage of having
a version control in place for development of your own stuff
immediately.
To install cdist, execute the following commands:
git clone git://git.schottelius.org/cdist
cd cdist
export PATH=$PATH:$(pwd -P)/bin
If you want to build and use the manpages, run:
./build man
export MANPATH=$MANPATH:$(pwd -P)/doc/man
#### Available versions in git
* The active development takes place in the **master** branch
* The current stable version can be found in the **2.0** branch
* The upcoming stable version can be found in the **2.1** branch
Other branches may be available for features or bugfixes, but they
may vanish at any point. To select a specific branch use
# Generic code
git checkout -b <localbranchname> origin/<branchname>
So for instance if you want to use and stay with version 2.0, you can use
git checkout -b 2.0 origin/2.0
#### Git Mirrors
If the main site is down, you can acquire cdist from one of the following sites:
* git://github.com/telmich/cdist.git ([github](https://github.com/telmich/cdist))
* git://git.code.sf.net/p/cdist/code ([sourceforge](https://sourceforge.net/p/cdist/code))
### Python Package
Cdist is available as a python package at
[PyPi](http://pypi.python.org/pypi/cdist/). You can install it using
pip install cdist
[[!tag cdist unix]]

View file

@ -0,0 +1,79 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>cdist(1)</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.77.1" /></head><body><div xml:lang="en" class="article" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="idp269184"></a>cdist(1)</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Nico</span> <span class="surname">Schottelius</span></h3><code class="email">&lt;<a class="email" href="mailto:nico-cdist--@--schottelius.org">nico-cdist--@--schottelius.org</a>&gt;</code></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#_name">1. NAME</a></span></dt><dt><span class="section"><a href="#_synopsis">2. SYNOPSIS</a></span></dt><dt><span class="section"><a href="#_description">3. DESCRIPTION</a></span></dt><dt><span class="section"><a href="#_banner">4. BANNER</a></span></dt><dt><span class="section"><a href="#_config">5. CONFIG</a></span></dt><dt><span class="section"><a href="#_examples">6. EXAMPLES</a></span></dt><dt><span class="section"><a href="#_environment">7. ENVIRONMENT</a></span></dt><dt><span class="section"><a href="#_exit_status">8. EXIT STATUS</a></span></dt><dt><span class="section"><a href="#_see_also">9. SEE ALSO</a></span></dt><dt><span class="section"><a href="#_copying">10. COPYING</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_name"></a>1. NAME</h2></div></div></div><p>cdist - Configuration management</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_synopsis"></a>2. SYNOPSIS</h2></div></div></div><p>cdist [-h] [-V]</p><p>cdist banner</p><p>cdist config [-h] [-d] [-V] [-c CDIST_HOME] [-i MANIFEST] [-p] [-s] host [host …]</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_description"></a>3. DESCRIPTION</h2></div></div></div><p>cdist is the frontend executable to the cdist configuration management.
cdist supports different as explained below. The options to the main
program are:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
-h, --help
</span></dt><dd>
Show the help screen
</dd><dt><span class="term">
-V, --version
</span></dt><dd>
Show version and exit
</dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_banner"></a>4. BANNER</h2></div></div></div><p>Displays the cdist banner.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_config"></a>5. CONFIG</h2></div></div></div><p>Configure a system</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
-h, --help
</span></dt><dd>
Show the help screen
</dd><dt><span class="term">
-c CDIST_HOME, --cdist-home CDIST_HOME
</span></dt><dd>
Instead of using the parent of the bin directory as cdist home,
use the specified directory
</dd><dt><span class="term">
-d, --debug
</span></dt><dd>
Enable debug output
</dd><dt><span class="term">
-i MANIFEST, --initial-manifest MANIFEST
</span></dt><dd>
Path to a cdist manifest or - to read from stdin
</dd><dt><span class="term">
-p, --parallel
</span></dt><dd>
Operate on multiple hosts in parallel
</dd><dt><span class="term">
-s, --sequential
</span></dt><dd>
Operate on multiple hosts sequentially
</dd></dl></div><p>--remote-copy REMOTE_COPY:
Command to use for remote copy (should behave like scp)</p><p>--remote-exec REMOTE_EXEC:
Command to use for remote execution (should behave like ssh)</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_examples"></a>6. EXAMPLES</h2></div></div></div><pre class="screen"># Configure ikq05.ethz.ch with debug enabled
cdist config -d ikq05.ethz.ch
# Configure hosts in parallel and use a different home 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</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_environment"></a>7. ENVIRONMENT</h2></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
TMPDIR, TEMP, TMP
</span></dt><dd>
Setup the base directory for the temporary directory.
See <a class="ulink" href="http://docs.python.org/py3k/library/tempfile.html" target="_top">http://docs.python.org/py3k/library/tempfile.html</a> for
more information. This is rather useful, if the standard
directory used does not allow executables.
</dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_exit_status"></a>8. EXIT STATUS</h2></div></div></div><p>The following exit values shall be returned:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
0
</span></dt><dd>
Successful completion
</dd><dt><span class="term">
1
</span></dt><dd>
One or more host configurations failed
</dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_see_also"></a>9. SEE ALSO</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
cdist(7)
</li><li class="listitem">
cdist-reference(7)
</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_copying"></a>10. COPYING</h2></div></div></div><p>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).</p></div></div></body></html>

View file

@ -0,0 +1,314 @@
/*
CSS stylesheet for XHTML produced by DocBook XSL stylesheets.
Tested with XSL stylesheets 1.61.2, 1.67.2
*/
span.strong {
font-weight: bold;
}
body blockquote {
margin-top: .75em;
line-height: 1.5;
margin-bottom: .75em;
}
html body {
margin: 1em 5% 1em 5%;
line-height: 1.2;
}
body div {
margin: 0;
}
h1, h2, h3, h4, h5, h6
{
color: #527bbd;
font-family: tahoma, verdana, sans-serif;
}
div.toc p:first-child,
div.list-of-figures p:first-child,
div.list-of-tables p:first-child,
div.list-of-examples p:first-child,
div.example p.title,
div.sidebar p.title
{
font-weight: bold;
color: #527bbd;
font-family: tahoma, verdana, sans-serif;
margin-bottom: 0.2em;
}
body h1 {
margin: .0em 0 0 -4%;
line-height: 1.3;
border-bottom: 2px solid silver;
}
body h2 {
margin: 0.5em 0 0 -4%;
line-height: 1.3;
border-bottom: 2px solid silver;
}
body h3 {
margin: .8em 0 0 -3%;
line-height: 1.3;
}
body h4 {
margin: .8em 0 0 -3%;
line-height: 1.3;
}
body h5 {
margin: .8em 0 0 -2%;
line-height: 1.3;
}
body h6 {
margin: .8em 0 0 -1%;
line-height: 1.3;
}
body hr {
border: none; /* Broken on IE6 */
}
div.footnotes hr {
border: 1px solid silver;
}
div.navheader th, div.navheader td, div.navfooter td {
font-family: sans-serif;
font-size: 0.9em;
font-weight: bold;
color: #527bbd;
}
div.navheader img, div.navfooter img {
border-style: none;
}
div.navheader a, div.navfooter a {
font-weight: normal;
}
div.navfooter hr {
border: 1px solid silver;
}
body td {
line-height: 1.2
}
body th {
line-height: 1.2;
}
ol {
line-height: 1.2;
}
ul, body dir, body menu {
line-height: 1.2;
}
html {
margin: 0;
padding: 0;
}
body h1, body h2, body h3, body h4, body h5, body h6 {
margin-left: 0
}
body pre {
margin: 0.5em 10% 0.5em 1em;
line-height: 1.0;
color: navy;
}
tt.literal, code.literal {
color: navy;
}
.programlisting, .screen {
border: 1px solid silver;
background: #f4f4f4;
margin: 0.5em 10% 0.5em 0;
padding: 0.5em 1em;
}
div.sidebar {
background: #ffffee;
margin: 1.0em 10% 0.5em 0;
padding: 0.5em 1em;
border: 1px solid silver;
}
div.sidebar * { padding: 0; }
div.sidebar div { margin: 0; }
div.sidebar p.title {
margin-top: 0.5em;
margin-bottom: 0.2em;
}
div.bibliomixed {
margin: 0.5em 5% 0.5em 1em;
}
div.glossary dt {
font-weight: bold;
}
div.glossary dd p {
margin-top: 0.2em;
}
dl {
margin: .8em 0;
line-height: 1.2;
}
dt {
margin-top: 0.5em;
}
dt span.term {
font-style: normal;
color: navy;
}
div.variablelist dd p {
margin-top: 0;
}
div.itemizedlist li, div.orderedlist li {
margin-left: -0.8em;
margin-top: 0.5em;
}
ul, ol {
list-style-position: outside;
}
div.sidebar ul, div.sidebar ol {
margin-left: 2.8em;
}
div.itemizedlist p.title,
div.orderedlist p.title,
div.variablelist p.title
{
margin-bottom: -0.8em;
}
div.revhistory table {
border-collapse: collapse;
border: none;
}
div.revhistory th {
border: none;
color: #527bbd;
font-family: tahoma, verdana, sans-serif;
}
div.revhistory td {
border: 1px solid silver;
}
/* Keep TOC and index lines close together. */
div.toc dl, div.toc dt,
div.list-of-figures dl, div.list-of-figures dt,
div.list-of-tables dl, div.list-of-tables dt,
div.indexdiv dl, div.indexdiv dt
{
line-height: normal;
margin-top: 0;
margin-bottom: 0;
}
/*
Table styling does not work because of overriding attributes in
generated HTML.
*/
div.table table,
div.informaltable table
{
margin-left: 0;
margin-right: 5%;
margin-bottom: 0.8em;
}
div.informaltable table
{
margin-top: 0.4em
}
div.table thead,
div.table tfoot,
div.table tbody,
div.informaltable thead,
div.informaltable tfoot,
div.informaltable tbody
{
/* No effect in IE6. */
border-top: 3px solid #527bbd;
border-bottom: 3px solid #527bbd;
}
div.table thead, div.table tfoot,
div.informaltable thead, div.informaltable tfoot
{
font-weight: bold;
}
div.mediaobject img {
margin-bottom: 0.8em;
}
div.figure p.title,
div.table p.title
{
margin-top: 1em;
margin-bottom: 0.4em;
}
div.calloutlist p
{
margin-top: 0em;
margin-bottom: 0.4em;
}
@media print {
div.navheader, div.navfooter { display: none; }
}
span.aqua { color: aqua; }
span.black { color: black; }
span.blue { color: blue; }
span.fuchsia { color: fuchsia; }
span.gray { color: gray; }
span.green { color: green; }
span.lime { color: lime; }
span.maroon { color: maroon; }
span.navy { color: navy; }
span.olive { color: olive; }
span.purple { color: purple; }
span.red { color: red; }
span.silver { color: silver; }
span.teal { color: teal; }
span.white { color: white; }
span.yellow { color: yellow; }
span.aqua-background { background: aqua; }
span.black-background { background: black; }
span.blue-background { background: blue; }
span.fuchsia-background { background: fuchsia; }
span.gray-background { background: gray; }
span.green-background { background: green; }
span.lime-background { background: lime; }
span.maroon-background { background: maroon; }
span.navy-background { background: navy; }
span.olive-background { background: olive; }
span.purple-background { background: purple; }
span.red-background { background: red; }
span.silver-background { background: silver; }
span.teal-background { background: teal; }
span.white-background { background: white; }
span.yellow-background { background: yellow; }
span.big { font-size: 2em; }
span.small { font-size: 0.6em; }

View file

@ -0,0 +1,126 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>cdist-best-practice(7)</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.77.1" /></head><body><div xml:lang="en" class="article" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="idp196592"></a>cdist-best-practice(7)</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Nico</span> <span class="surname">Schottelius</span></h3><code class="email">&lt;<a class="email" href="mailto:nico-cdist--@--schottelius.org">nico-cdist--@--schottelius.org</a>&gt;</code></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#_name">1. NAME</a></span></dt><dt><span class="section"><a href="#_passwordless_connections">2. PASSWORDLESS CONNECTIONS</a></span></dt><dt><span class="section"><a href="#_speeding_up_ssh_connections">3. SPEEDING UP SSH CONNECTIONS</a></span></dt><dt><span class="section"><a href="#_multi_master_or_environment_setups">4. MULTI MASTER OR ENVIRONMENT SETUPS</a></span></dt><dt><span class="section"><a href="#_seperating_work_by_groups">5. SEPERATING WORK BY GROUPS</a></span></dt><dt><span class="section"><a href="#_maintaining_multiple_configurations">6. MAINTAINING MULTIPLE CONFIGURATIONS</a></span></dt><dt><span class="section"><a href="#_multiple_developers_with_different_trust">7. MULTIPLE DEVELOPERS WITH DIFFERENT TRUST</a></span></dt><dt><span class="section"><a href="#_templating">8. TEMPLATING</a></span></dt><dt><span class="section"><a href="#_see_also">9. SEE ALSO</a></span></dt><dt><span class="section"><a href="#_copying">10. COPYING</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_name"></a>1. NAME</h2></div></div></div><p>cdist-best-practice - Practices used in real environments</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_passwordless_connections"></a>2. PASSWORDLESS CONNECTIONS</h2></div></div></div><p>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).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_speeding_up_ssh_connections"></a>3. SPEEDING UP SSH CONNECTIONS</h2></div></div></div><p>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:</p><pre class="screen">Host *
ControlPath ~/.ssh/master-%l-%r@%h:%p
ControlMaster auto
ControlPersist 10</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_multi_master_or_environment_setups"></a>4. MULTI MASTER OR ENVIRONMENT SETUPS</h2></div></div></div><p>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:</p><pre class="screen"># 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</pre><p>Similar if you want to have cdist checked out at multiple machines,
you can clone it multiple times:</p><pre class="screen">machine-a % git clone git://your-git-server/cdist
machine-b % git clone git://your-git-server/cdist</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_seperating_work_by_groups"></a>5. SEPERATING WORK BY GROUPS</h2></div></div></div><p>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
<span class="strong"><strong>conf/manifests/init</strong></span>:</p><pre class="screen"># Include other groups
sh -e "$__manifest/systems"
sh -e "$__manifest/cbrg"</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_maintaining_multiple_configurations"></a>6. MAINTAINING MULTIPLE CONFIGURATIONS</h2></div></div></div><p>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:</p><pre class="screen"># 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</pre><p>The following <span class="strong"><strong>.git/config</strong></span> is taken from a a real world scenario:</p><pre class="screen"># 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</pre><p>Have a look at git-remote(1) to adjust the remote configuration, which allows</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_multiple_developers_with_different_trust"></a>7. MULTIPLE DEVELOPERS WITH DIFFERENT TRUST</h2></div></div></div><p>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:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
Create a dedicated user (for instance <span class="strong"><strong>cdist</strong></span>)
</li><li class="listitem">
Setup the ssh-pubkey for this user that has the right to configure all hosts
</li><li class="listitem">
Create a wrapper to update the cdist configuration in ~cdist/cdist
</li><li class="listitem">
Allow every developer to execute this script via sudo as the user cdist
</li><li class="listitem">
Allow run of cdist as user cdist on specific hosts on a per user/group base
</li><li class="listitem">
f.i. nico ALL=(ALL) NOPASSWD: /home/cdist/bin/cdist config hostabc
</li></ul></div><p>For more details consult sudoers(5)</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_templating"></a>8. TEMPLATING</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
create directory templates/ in your type (convention)
</li><li class="listitem">
create the template as an executable file like templates/basic.conf.sh, it will output text using shell variables for the values
</li></ul></div><pre class="screen">#!/bin/sh
# in the template, use cat &lt;&lt; eof (here document) to output the text
# and use standard shell variables in the template
# output everything in the template script to stdout
cat &lt;&lt; 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</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
in the manifest, export the relevant variables and add the following lines in your manifest:
</li></ul></div><pre class="screen"># 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" &gt; "$__object/files/basic.conf"
# send the rendered template
__file /etc/nginx/sites-available/test.conf --state present --source "$__object/files/basic.conf"</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_see_also"></a>9. SEE ALSO</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
cdist(1)
</li><li class="listitem">
cdist-tutorial(7)
</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_copying"></a>10. COPYING</h2></div></div></div><p>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).</p></div></div></body></html>

View file

@ -0,0 +1,77 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>cdist-bootstrap(7)</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.77.1" /></head><body><div xml:lang="en" class="article" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="idp191328"></a>cdist-bootstrap(7)</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Nico</span> <span class="surname">Schottelius</span></h3><code class="email">&lt;<a class="email" href="mailto:nico-cdist--@--schottelius.org">nico-cdist--@--schottelius.org</a>&gt;</code></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#_name">1. NAME</a></span></dt><dt><span class="section"><a href="#_introduction">2. INTRODUCTION</a></span></dt><dt><span class="section"><a href="#_location">3. LOCATION</a></span></dt><dt><span class="section"><a href="#_setup_working_directory_and_branch">4. SETUP WORKING DIRECTORY AND BRANCH</a></span></dt><dt><span class="section"><a href="#_publishing_the_configuration">5. PUBLISHING THE CONFIGURATION</a></span></dt><dt><span class="section"><a href="#_updating_from_origin">6. UPDATING FROM ORIGIN</a></span></dt><dt><span class="section"><a href="#_see_also">7. SEE ALSO</a></span></dt><dt><span class="section"><a href="#_copying">8. COPYING</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_name"></a>1. NAME</h2></div></div></div><p>cdist-bootstrap - setup cdist environment</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_introduction"></a>2. INTRODUCTION</h2></div></div></div><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_location"></a>3. LOCATION</h2></div></div></div><p>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.</p><p>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.</p><p>For more sophisticated setups developing cdist configurations with multiple
people, have a look at cdist-best-practice(7).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_setup_working_directory_and_branch"></a>4. SETUP WORKING DIRECTORY AND BRANCH</h2></div></div></div><p>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 dont).
Entering the command "git branch" should show you "* master", which indicates
you are on the <span class="strong"><strong>master</strong></span> branch.</p><p>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. Lets use <span class="strong"><strong>git branch -r</strong></span>
to list all branches:</p><pre class="screen">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 -&gt; origin/master
origin/archive_shell_function_approach
origin/master</pre><p>So <span class="strong"><strong>2.0</strong></span> 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 wont break your configuration when updating.</p><p>Its up to you decide on which branch you want to base your own work:
master contains more recent changes, newer types, but may also break.
The versions branches are stable, but thus may miss the latest features.
Your decision can be changed later on, but may result in merge conflicts,
which youd have to solve.</p><p>Lets assume you want latest stuff and select the master branch as base for
your own work. Now its 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.</p><p>In this tutorial I use the branch <span class="strong"><strong>mycompany</strong></span>:</p><pre class="screen">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</pre><p>From now on, you can use git as usual to commit your changes in your own branch.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_publishing_the_configuration"></a>5. PUBLISHING THE CONFIGURATION</h2></div></div></div><p>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:</p><pre class="screen"># 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</pre><p>Now you have setup the git repository to synchronise the <span class="strong"><strong>mycompany</strong></span>
branch with the <span class="strong"><strong>master</strong></span> branch on the host <span class="strong"><strong>loch</strong></span>. Thus you can commit
as usual in your branch and push out changes by entering <span class="strong"><strong><span class="strong"><strong>git push</strong></span></strong></span>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_updating_from_origin"></a>6. UPDATING FROM ORIGIN</h2></div></div></div><p>Whenever you want to update your cdist installation, you can use git to do so:</p><pre class="screen"># 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</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_see_also"></a>7. SEE ALSO</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
cdist(1)
</li><li class="listitem">
cdist-tutorial(7)
</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_copying"></a>8. COPYING</h2></div></div></div><p>Copyright (C) 2012 Nico Schottelius. Free use of this software is
granted under the terms of the GNU General Public License version 3 (GPLv3).</p></div></div></body></html>

View file

@ -0,0 +1,28 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>cdist-explorer(7)</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.77.1" /></head><body><div xml:lang="en" class="article" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="idp171136"></a>cdist-explorer(7)</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Nico</span> <span class="surname">Schottelius</span></h3><code class="email">&lt;<a class="email" href="mailto:nico-cdist--@--schottelius.org">nico-cdist--@--schottelius.org</a>&gt;</code></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#_name">1. NAME</a></span></dt><dt><span class="section"><a href="#_description">2. DESCRIPTION</a></span></dt><dt><span class="section"><a href="#_examples">3. EXAMPLES</a></span></dt><dt><span class="section"><a href="#_see_also">4. SEE ALSO</a></span></dt><dt><span class="section"><a href="#_copying">5. COPYING</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_name"></a>1. NAME</h2></div></div></div><p>cdist-explorer - Explore the target systems</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_description"></a>2. DESCRIPTION</h2></div></div></div><p>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.</p><p>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.</p><p>Explorers can reuse other explorers on the target system by calling
$<span class="emphasis"><em>explorer/&lt;explorer_name&gt; (general and type explorer) or
$</em></span>type_explorer/&lt;explorer name&gt; (type explorer).</p><p>In case of significant errors, the explorer may exit non-zero and return an
error message on stderr, which will cause cdist to abort.</p><p>You can also use stderr for debugging purposes while developing a new
explorer.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_examples"></a>3. EXAMPLES</h2></div></div></div><p>A very simple explorer may look like this:</p><pre class="screen">hostname</pre><p>Which is in practise the <span class="strong"><strong><span class="strong"><strong>hostname</strong></span></strong></span> explorer.</p><p>A type explorer, which could check for the status of a package may look like this:</p><pre class="screen">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&gt;/dev/null || exit 0</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_see_also"></a>4. SEE ALSO</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
cdist(1)
</li><li class="listitem">
cdist-reference(7)
</li><li class="listitem">
cdist-stages(7)
</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_copying"></a>5. COPYING</h2></div></div></div><p>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).</p></div></div></body></html>

View file

@ -0,0 +1,43 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>cdist-hacker(7)</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.77.1" /></head><body><div xml:lang="en" class="article" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="idp196496"></a>cdist-hacker(7)</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Nico</span> <span class="surname">Schottelius</span></h3><code class="email">&lt;<a class="email" href="mailto:nico-cdist--@--schottelius.org">nico-cdist--@--schottelius.org</a>&gt;</code></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#_name">1. NAME</a></span></dt><dt><span class="section"><a href="#_welcome">2. WELCOME</a></span></dt><dt><span class="section"><a href="#_reporting_bugs">3. REPORTING BUGS</a></span></dt><dt><span class="section"><a href="#_coding_conventions_everywhere">4. CODING CONVENTIONS (EVERYWHERE)</a></span></dt><dt><span class="section"><a href="#_how_to_submit_stuff_for_inclusion_into_upstream_cdist">5. HOW TO SUBMIT STUFF FOR INCLUSION INTO UPSTREAM CDIST</a></span></dt><dt><span class="section"><a href="#_how_to_submit_a_new_type">6. HOW TO SUBMIT A NEW TYPE</a></span></dt><dt><span class="section"><a href="#_see_also">7. SEE ALSO</a></span></dt><dt><span class="section"><a href="#_copying">8. COPYING</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_name"></a>1. NAME</h2></div></div></div><p>cdist-hacker - How to get (stuff) into cdist</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_welcome"></a>2. WELCOME</h2></div></div></div><p>Welcome dear hacker! I invite you to a tour of pointers to
get into the usable configuration mangament system, cdist.</p><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_reporting_bugs"></a>3. REPORTING BUGS</h2></div></div></div><p>If you believe youve 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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_coding_conventions_everywhere"></a>4. CODING CONVENTIONS (EVERYWHERE)</h2></div></div></div><p>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.</p><p>Indention is 4 spaces (welcome to the python world).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_how_to_submit_stuff_for_inclusion_into_upstream_cdist"></a>5. HOW TO SUBMIT STUFF FOR INCLUSION INTO UPSTREAM CDIST</h2></div></div></div><p>If you did some cool changes to cdist, which you value as a benefit for
everybody using cdist, youre welcome to propose inclusion into upstream.</p><p>There are though some requirements to ensure your changes dont break others
work nor kill the authors brain:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
All files should contain the usual header (Author, Copying, etc.)
</li><li class="listitem">
Code submission must be done via git
</li><li class="listitem">
Do not add conf/manifest/init - This file should only be touched in your
private branch!
</li><li class="listitem">
Code to be included should be branched of the upstream "master" branch
</li><li class="listitem">
Exception: Bugfixes to a version branch
</li><li class="listitem">
On a merge request, always name the branch I should pull from
</li><li class="listitem">
Always ensure <span class="strong"><strong>all</strong></span> manpages build. Use <span class="strong"><strong>./build man</strong></span> to test.
</li><li class="listitem">
If you developed more than <span class="strong"><strong>one</strong></span> feature, consider submitting them in
seperate branches. This way one feature can already be included, even if
the other needs to be improved.
</li></ul></div><p>As soon as your work meets these requirements, write a mail
for inclusion to the mailinglist <span class="strong"><strong>cdist at cdistatl.schottelius.org</strong></span>
or open a pull request at <a class="ulink" href="http://github.com/telmich/cdist" target="_top">http://github.com/telmich/cdist</a>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_how_to_submit_a_new_type"></a>6. HOW TO SUBMIT A NEW TYPE</h2></div></div></div><p>For detailled information about types, see cdist-type(7).</p><p>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).</p><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_see_also"></a>7. SEE ALSO</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
cdist(7)
</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_copying"></a>8. COPYING</h2></div></div></div><p>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).</p></div></div></body></html>

View file

@ -0,0 +1,72 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>cdist-manifest(7)</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.77.1" /></head><body><div xml:lang="en" class="article" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="idp196960"></a>cdist-manifest(7)</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Nico</span> <span class="surname">Schottelius</span></h3><code class="email">&lt;<a class="email" href="mailto:nico-cdist--@--schottelius.org">nico-cdist--@--schottelius.org</a>&gt;</code></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#_name">1. NAME</a></span></dt><dt><span class="section"><a href="#_description">2. DESCRIPTION</a></span></dt><dt><span class="section"><a href="#_initial_and_type_manifests">3. INITIAL AND TYPE MANIFESTS</a></span></dt><dt><span class="section"><a href="#_define_state_in_the_initial_manifest">4. DEFINE STATE IN THE INITIAL MANIFEST</a></span></dt><dt><span class="section"><a href="#_splitting_up_the_initial_manifest">5. SPLITTING UP THE INITIAL MANIFEST</a></span></dt><dt><span class="section"><a href="#_dependencies">6. DEPENDENCIES</a></span></dt><dt><span class="section"><a href="#_examples">7. EXAMPLES</a></span></dt><dt><span class="section"><a href="#_see_also">8. SEE ALSO</a></span></dt><dt><span class="section"><a href="#_copying">9. COPYING</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_name"></a>1. NAME</h2></div></div></div><p>cdist-manifest - (Re-)Use types</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_description"></a>2. DESCRIPTION</h2></div></div></div><p>Manifests are used to define which objects to create.
Objects are instances of <span class="strong"><strong>types</strong></span>, like in object orientated programming languages.
An object is represented by the combination of
<span class="strong"><strong>type + slash + object name</strong></span>: <span class="strong"><strong><span class="emphasis"><em>file/etc/cdist-configured</em></span> is an
object of the type <span class="strong"><strong><span class="strong"><strong></strong></span>file</strong></span></strong></span> with the name <span class="strong"><strong><span class="strong"><strong>etc/cdist-configured</strong></span></strong></span>.</p><p>All available types can be found in the <span class="strong"><strong>conf/type/</strong></span> directory,
use <span class="strong"><strong>ls conf/type</strong></span> to get the list of available types. If you have
setup the MANPATH correctly, you can use <span class="strong"><strong>man cdist-reference</strong></span> to access
the reference with pointers to the manpages.</p><p>Types in manifests are used like normal command line tools. Lets have a look
at an example:</p><pre class="screen"># Create object of type __package with the parameter state = removed
__package apache2 --state removed
# Same with the __directory type
__directory /tmp/cdist --state present</pre><p>These two lines create objects, which will later be used to realise the
configuration on the target host.</p><p>Manifests are executed locally as a shell script using <span class="strong"><strong>/bin/sh -e</strong></span>.
The resulting objects are stored in an internal database.</p><p>The same object can be redefined in multiple different manifests as long as
the parameters are exactly the same.</p><p>In general, manifests are used to define which types are used depending
on given conditions.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_initial_and_type_manifests"></a>3. INITIAL AND TYPE MANIFESTS</h2></div></div></div><p>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).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_define_state_in_the_initial_manifest"></a>4. DEFINE STATE IN THE INITIAL MANIFEST</h2></div></div></div><p>The <span class="strong"><strong>initial manifest</strong></span> is the entry point for cdist to find out, which
<span class="strong"><strong>objects</strong></span> to configure on the selected host.
Cdist searches for the initial manifest at <span class="strong"><strong>conf/manifest/init</strong></span>.</p><p>Within this initial manifest, you define, which objects should be
created on which host. To distinguish between hosts, you can use the
environment variable <span class="strong"><strong>__target_host</strong></span>. Lets have a look at a simple
example:</p><pre class="screen">__cdistmarker
case "$__target_host" in
localhost)
__directory /home/services/kvm-vm --parents yes
;;
esac</pre><p>This manifest says: Independent of the host, always use the type
<span class="strong"><strong><span class="strong"><strong>__cdistmarker</strong></span></strong></span>, which creates the file <span class="strong"><strong>/etc/cdist-configured</strong></span>,
with the timestamp as content.
The directory <span class="strong"><strong><span class="strong"><strong>/home/services/kvm-vm</strong></span></strong></span>, including all parent directories,
is only created on the host <span class="strong"><strong><span class="strong"><strong>localhost</strong></span></strong></span>.</p><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_splitting_up_the_initial_manifest"></a>5. SPLITTING UP THE INITIAL MANIFEST</h2></div></div></div><p>If you want to split up your initial manifest, you can create other shell
scripts in <span class="strong"><strong>conf/manifest/</strong></span> and include them in <span class="strong"><strong>conf/manifest/init</strong></span>.
Cdist provides the environment variable <span class="strong"><strong><span class="strong"><strong>__manifest</strong></span></strong></span> to reference to
the directory containing the initial manifest (see cdist-reference(7)).</p><p>The following example would include every file with a <span class="strong"><strong>.sh</strong></span> suffix:</p><pre class="screen"># Include *.sh
for manifest in $__manifest/*.sh; do
# And source scripts into our shell environment
. "$manifest"
done</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_dependencies"></a>6. DEPENDENCIES</h2></div></div></div><p>If you want to describe that something requires something else, just
setup the variable "require" to contain the requirements. Multiple
requirements can be added white space seperated.</p><pre class="screen"># 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</pre><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_examples"></a>7. EXAMPLES</h2></div></div></div><p>The initial manifest may for instance contain the following code:</p><pre class="screen"># 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</pre><p>The manifest of the type "nologin" may look like this:</p><pre class="screen">__file /etc/nologin --type file --source "$__type/files/default.nologin"</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_see_also"></a>8. SEE ALSO</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
cdist-tutorial(7)
</li><li class="listitem">
cdist-type(7)
</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_copying"></a>9. COPYING</h2></div></div></div><p>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).</p></div></div></body></html>

View file

@ -0,0 +1,51 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>cdist-quickstart(7)</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.77.1" /></head><body><div xml:lang="en" class="article" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="idp198976"></a>cdist-quickstart(7)</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Nico</span> <span class="surname">Schottelius</span></h3><code class="email">&lt;<a class="email" href="mailto:nico-cdist--@--schottelius.org">nico-cdist--@--schottelius.org</a>&gt;</code></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#_name">1. NAME</a></span></dt><dt><span class="section"><a href="#_introduction">2. INTRODUCTION</a></span></dt><dt><span class="section"><a href="#_quick_start_get_your_hands_dirty_now">3. QUICK START - GET YOUR HANDS DIRTY NOW</a></span></dt><dt><span class="section"><a href="#_see_also">4. SEE ALSO</a></span></dt><dt><span class="section"><a href="#_copying">5. COPYING</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_name"></a>1. NAME</h2></div></div></div><p>cdist-quickstart - jump in and enjoy cdist</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_introduction"></a>2. INTRODUCTION</h2></div></div></div><p>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.</p><p>This tutorial assumes you are configuring <span class="strong"><strong>localhost</strong></span>, because
it is always available. Just replace <span class="strong"><strong>localhost</strong></span> with your target
host for real life usage.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_quick_start_get_your_hands_dirty_now"></a>3. QUICK START - GET YOUR HANDS DIRTY NOW</h2></div></div></div><p>For those who just want to configure a system with the
cdist configuration management and do not need (or want)
to understand everything.</p><p>Cdist uses <span class="strong"><strong>ssh</strong></span> for communication and transportation
and usually logs into the <span class="strong"><strong>target host</strong></span> as the
<span class="strong"><strong>root</strong></span> user. So you need to configure the <span class="strong"><strong>ssh server</strong></span>
of the target host to allow root logins: Edit
the file <span class="strong"><strong>/etc/ssh/sshd_config</strong></span> and add one of the following
lines:</p><pre class="screen"># Allow login only via public key
PermitRootLogin without-password
# Allow login via password and public key
PermitRootLogin yes</pre><p>As cdist uses ssh intensively, it is recommended to setup authentication
with public keys:</p><pre class="screen"># Generate pubkey pair as a normal user
ssh-keygen
# Copy pubkey over to target host
ssh-copy-id root@localhost</pre><p>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:</p><pre class="screen"># Start agent and export variables
eval `ssh-agent`
# Add keys (requires password for every identity file)
ssh-add</pre><p>At this point you should be able to <span class="strong"><strong><span class="strong"><strong>ssh root@localhost</strong></span></strong></span> without
re-entering the password. If something failed until here, ensure that
all steps went successfully and you have read and understood the
documentation.</p><p>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:</p><pre class="screen"># Get cdist
git clone git://git.schottelius.org/cdist
# Create manifest (maps configuration to host(s)
cd cdist
echo '__file /etc/cdist-configured' &gt; 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</pre><p>Thats it, youve 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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_see_also"></a>4. SEE ALSO</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
cdist(1)
</li><li class="listitem">
cdist-tutorial(7)
</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_copying"></a>5. COPYING</h2></div></div></div><p>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).</p></div></div></body></html>

View file

@ -0,0 +1,249 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>cdist-reference(7)</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.77.1" /></head><body><div xml:lang="en" class="article" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="idp198320"></a>cdist-reference(7)</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Nico</span> <span class="surname">Schottelius</span></h3><code class="email">&lt;<a class="email" href="mailto:nico-cdist--@--schottelius.org">nico-cdist--@--schottelius.org</a>&gt;</code></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#_name">1. NAME</a></span></dt><dt><span class="section"><a href="#_explorers">2. EXPLORERS</a></span></dt><dt><span class="section"><a href="#_paths">3. PATHS</a></span></dt><dt><span class="section"><a href="#_types">4. TYPES</a></span></dt><dt><span class="section"><a href="#_objects">5. OBJECTS</a></span></dt><dt><span class="section"><a href="#_environment_variables">6. ENVIRONMENT VARIABLES</a></span></dt><dt><span class="section"><a href="#_see_also">7. SEE ALSO</a></span></dt><dt><span class="section"><a href="#_copying">8. COPYING</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_name"></a>1. NAME</h2></div></div></div><p>cdist-reference - Variable, path and type reference for cdist</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_explorers"></a>2. EXPLORERS</h2></div></div></div><p>The following global explorers are available:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
hostname
</li><li class="listitem">
interfaces
</li><li class="listitem">
lsb_codename
</li><li class="listitem">
lsb_description
</li><li class="listitem">
lsb_id
</li><li class="listitem">
lsb_release
</li><li class="listitem">
machine
</li><li class="listitem">
os
</li><li class="listitem">
os_version
</li><li class="listitem">
runlevel
</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_paths"></a>3. PATHS</h2></div></div></div><p>If not specified otherwise, all paths are relative to the checkout directory.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
conf/
</span></dt><dd>
Contains the (static) configuration like manifests, types and explorers.
</dd><dt><span class="term">
conf/manifest/init
</span></dt><dd>
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.
</dd><dt><span class="term">
conf/manifest/*
</span></dt><dd>
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.
</dd><dt><span class="term">
conf/explorer/&lt;name&gt;
</span></dt><dd>
Contains explorers to be run on the target hosts, see cdist-explorer(7).
</dd><dt><span class="term">
conf/type/
</span></dt><dd>
Contains all available types, which are used to provide
some kind of functionality. See cdist-type(7).
</dd><dt><span class="term">
conf/type/&lt;name&gt;/
</span></dt><dd><p class="simpara">
Home of the type &lt;name&gt;.
</p><pre class="literallayout">This directory is referenced by the variable __type (see below).</pre></dd><dt><span class="term">
conf/type/&lt;name&gt;/man.text
</span></dt><dd>
Manpage in Asciidoc format (required for inclusion into upstream)
</dd><dt><span class="term">
conf/type/&lt;name&gt;/manifest
</span></dt><dd>
Used to generate additional objects from a type.
</dd><dt><span class="term">
conf/type/&lt;name&gt;/gencode-local
</span></dt><dd>
Used to generate code to be executed on the source host
</dd><dt><span class="term">
conf/type/&lt;name&gt;/gencode-remote
</span></dt><dd>
Used to generate code to be executed on the target host
</dd><dt><span class="term">
conf/type/&lt;name&gt;/parameter/required
</span></dt><dd>
Parameters required by type, \n seperated list.
</dd><dt><span class="term">
conf/type/&lt;name&gt;/parameter/optional
</span></dt><dd>
Parameters optionally accepted by type, \n seperated list.
</dd><dt><span class="term">
conf/type/&lt;name&gt;/parameter/boolean
</span></dt><dd>
Boolean parameters accepted by type, \n seperated list.
</dd><dt><span class="term">
conf/type/&lt;name&gt;/explorer
</span></dt><dd>
Location of the type specific explorers.
This directory is referenced by the variable __type_explorer (see below).
See cdist-explorer(7).
</dd><dt><span class="term">
out/