cdist/REAL_README

[[!meta title="cdist - configuration management"]]

     
                 ..          .       .x+=:.        s   
               dF           @88>    z`    ^%      :8  
              '88bu.        %8P        .   <k    .88 
          .   '*88888bu      .       .@8Ned8"   :888ooo
     .udR88N    ^"*8888N   .@88u   .@^%8888"  -*8888888
    <888'888k  beWE "888L ''888E` x88:  `)8b.   8888
    9888 'Y"   888E  888E   888E  8888N=*8888   8888
    9888       888E  888E   888E   %8"    R88   8888
    9888       888E  888F   888E    @8Wou 9%   .8888Lu=
    ?8888u../ .888N..888    888&  .888888P`    ^%888*
     "8888P'   `"888*""     R888" `   ^"F        'Y" 
       "P'        ""         ""  
     

[[!toc  levels=2]]

## Introduction

cdist configures your system and is similar 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/)
and [puppet](http://www.puppetlabs.com/), but
it ticks differently:

 * cdist sticks completly to the KISS (keep it simple and stupid) paradigma
  * cdist's core is very small (< 1k lines of code)
  * There is only one type to extend cdist called ***type***.
  * One main development target: ***It must be incredible easy to add new types.***
 * cdist is UNIX
  * It reuses existing tools like cat, find, mv, ...
  * cdist's documentation is bundled as manpages
 * cdist is written in POSIX shell
  * No special requirements like high level interpreters needed on server or target

### Architecture

 * Push mode (server pushes configuration)
 * Pull mode planned (client triggers configuration)
 * User defines configuration in shell scripts (called ***manifests***)
 * Generates internal configuration (cconfig style)
 * Uses ***types*** to generate code be executed on the target
 * And finally executes the code on the target / applies the configuration

### Features

Stuff that should probably be included in every configuration management,
but is not. Or: The reason why I began to write cdist.

 * Speed
 * Elegant code
 * Clean design
 * Good documentation (man pages)
 * Meaningful error messages
 * No surprise factor
 * Consistency in behaviour, naming and documentation
 * Easy integration nacked installations
 * Simple and well-known DSL: posix shell
 * It is very easy to
  * extend cdist
  * debug cdist-core and cdist-types
 * Focus on reuse of existing functionality
  * ssh
  * sh
  * find, rm, ...

## Requirements

### Server

 * A posix like shell
 * SSH-Client

### Client ("target host")

 * A posix like shell
 * SSH-Server


## Getting cdist

You can clone cdist from git, which gives you the advantage of having
a version control in place for development of your own stuff as well.

### Installation

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 the manpages (requires asciidoc to be installed)
    make man
    export MANPATH=$MANPATH:$(pwd -P)/doc/man


Afterwards you can run ***cdist-quickstart*** to get an impression on
how to use cdist.

### Available versions

There are at least two branches available:

 * master: the development branch
 * 1.0: stable branch of version 1.0

Other branches may be available as well for features or bugfixes, but they
may vanish at any point. To select a specific branch use

    # Generic code
    git checkout -b <name> origin/<name>
    
    # Stay on version 1.0
    git checkout -b 1.0 origin/1.0

### Update

To upgrade cdist in the current branch use

    git pull

    # Also update the manpages
    make man
    export MANPATH=$MANPATH:$(pwd -P)/doc/man


The version branches are designed to change if there are incompatibilities.
Or the other way round: As long as you stay on 1.0 and do git pull, nothing
should break.

## Support

### IRC

You can join the development ***IRC channel***
[#cLinux on irc.freenode.org](irc://irc.freenode.org/#cLinux).

### Mailing list

Bug reports, questions, patches, etc. should be send to the
[cdist mailing list](http://l.schottelius.org/mailman/listinfo/cdist).

## Used by

If you're using cdist, feel free to send a report to the mailing list.
Interesting information are for instance

 * Which services do you manage?
 * How many machines do you manage?
 * What are the pros/cons you see in cdist?
 * General comments/critics

### Nico Schottelius, Systems Group ETH Zurich

Yes, I'm actually eating my own dogfood and currently managing

 * [plone](http://plone.org/) (cms)
 * [moinmoin](http://moinmo.in/) (wiki)
 * [apache](http://httpd.apache.org/) (webserver)
 * [kerberos (mit)](http://web.mit.edu/kerberos/) (authentication)
 * [ircd-hybrid](http://www.ircd-hybrid.org/) (chat)
 * [stunnel](http://stunnel.mirt.net/) (SSL tunnel)

with cdist on a total of **3** production servers of the
[Systems Group](http://www.systems.ethz.ch) at the
[ETH Zurich](http://www.ethz.ch).