README 10.5 KB
Newer Older
Nico Schottelius's avatar
Nico Schottelius committed
1
[[!meta title="cdist - usable configuration management"]]
Nico Schottelius's avatar
Nico Schottelius committed
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

     
                 ..          .       .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'        ""         ""  
     

18
[[!toc levels=3]]
Nico Schottelius's avatar
Nico Schottelius committed
19 20 21

## Introduction

Nico Schottelius's avatar
Nico Schottelius committed
22 23 24
cdist is a usable configuration management system. It adheres to
the KISS principle and is being used in small up to enterprise grade
environments.
Nico Schottelius's avatar
Nico Schottelius committed
25
cdist is an alternative to other configuration management systems like
Nico Schottelius's avatar
Nico Schottelius committed
26 27 28
[cfengine](http://www.cfengine.org/),
[bcfg2](http://trac.mcs.anl.gov/projects/bcfg2),
[chef](http://wiki.opscode.com/display/chef/)
Nico Schottelius's avatar
Nico Schottelius committed
29 30
and [puppet](http://www.puppetlabs.com/).
But cdist ticks differently, here is the feature set that makes it unique: 
Nico Schottelius's avatar
Nico Schottelius committed
31 32

[[!table  data="""
Nico Schottelius's avatar
Nico Schottelius committed
33
Keywords | Description
Nico Schottelius's avatar
Nico Schottelius committed
34 35
Simplicity | There is only one type to extend cdist called ***type***
Design | Type and core cleanly seperated
Nico Schottelius's avatar
Nico Schottelius committed
36
Design | Sticks completly to the KISS (keep it simple and stupid) paradigma
Nico Schottelius's avatar
Nico Schottelius committed
37 38 39 40
Design | Meaningful error messages - do not lose time debugging error messages
Design | Consistency in behaviour, naming and documentation
Design | No surprise factor: Only do what is obviously clear, no magic
Design | Define target state, do not focus on methods or scripts
41
Design | Push architecture: Instantly apply your changes
Nico Schottelius's avatar
Nico Schottelius committed
42 43
Small core | cdist's core is very small - less code, less bugs
Fast development | Focus on straightforwardness of type creation is a main development objective
Nico Schottelius's avatar
Nico Schottelius committed
44
Fast development | Batteries included: A lot of requirements can be solved using standard types
Nico Schottelius's avatar
Nico Schottelius committed
45
Modern Programming Language | cdist is written in Python
Nico Schottelius's avatar
Nico Schottelius committed
46 47
Requirements, Scalability | No central server needed, cdist operates in push mode and can be run from any computer
Requirements, Scalability, Upgrade | cdist only needs to be updated on the master, not on the target hosts
Nico Schottelius's avatar
Nico Schottelius committed
48 49
Requirements, Security | Uses well-know [SSH](http://www.openssh.com/) as transport protocol
Requirements, Simplicity | Requires only shell and SSH server on the target
Nico Schottelius's avatar
Nico Schottelius committed
50 51 52 53
UNIX | Reuse of existing tools like cat, find, mv, ...
UNIX, familar environment, documentation | Is available as manpages and HTML
UNIX, simplicity, familar environment | cdist is configured in POSIX shell
"""]]
Nico Schottelius's avatar
Nico Schottelius committed
54

55 56
### Documentation

57 58
The cdist documentation is included as manpages in the distribution.  
You can browse the documentation online as well:
Nico Schottelius's avatar
Nico Schottelius committed
59

60 61
 * [latest version](man/latest)
 * [all versions (>= 2.0.4)](man)
62

63 64 65 66 67 68
### OS support

cdist was tested or is know to run on at least

 * [Archlinux](http://www.archlinux.org/)
 * [Debian](http://www.debian.org/)
69
 * [CentOS](http://www.centos.org/)
Nico Schottelius's avatar
Nico Schottelius committed
70
 * [Fedora](http://fedoraproject.org/)
71 72
 * [Gentoo](http://www.gentoo.org/)
 * [Mac OS X](http://www.apple.com/macosx/)
73
 * [OpenBSD](http://www.openbsd.org)
Nico Schottelius's avatar
Nico Schottelius committed
74
 * [Redhat](http://www.redhat.com/)
75
 * [Ubuntu](http://www.ubuntu.com/)
76
 * [XenServer](http://www.citrix.com/xenserver/)
77

Nico Schottelius's avatar
Nico Schottelius committed
78 79 80 81 82 83

## Requirements

### Server

 * A posix like shell
Nico Schottelius's avatar
Nico Schottelius committed
84
 * Python (>= 3.2 required)
Nico Schottelius's avatar
Nico Schottelius committed
85
 * SSH client
86
 * Asciidoc (for building the manpages)
Nico Schottelius's avatar
Nico Schottelius committed
87 88 89 90

### Client ("target host")

 * A posix like shell
Nico Schottelius's avatar
Nico Schottelius committed
91
 * SSH server
Nico Schottelius's avatar
Nico Schottelius committed
92 93


94
## Installation
Nico Schottelius's avatar
Nico Schottelius committed
95

96
### Preparation
97

98 99
Ensure you have Python 3.2 installed on the machine you use to **deploy to the targets**
(the ***source host***).
100

Nico Schottelius's avatar
Nico Schottelius committed
101 102 103 104 105 106
#### Archlinux

Archlinux already has python >= 3.2, so you only need to do:

    pacman -S python

107 108 109 110
#### CentOS

See the "From source" section

111
#### Debian
Nico Schottelius's avatar
Nico Schottelius committed
112

113
For Debian >= wheezy:
Nico Schottelius's avatar
Nico Schottelius committed
114

115 116
    aptitude install python3

117 118 119 120
On squeeze you can add following line in **/etc/apt/sources.list**

  deb http://ftp.debian.org/debian wheezy main

Nico Schottelius's avatar
Nico Schottelius committed
121
And add pinning entry in **/etc/apt/preferences.d/wheezy**:
122 123 124 125 126 127

  Package: *
  Pin: release n=wheezy
  Pin-Priority: 1

Please be aware that both **openssh-server** and **openssh-client** might be
Nico Schottelius's avatar
Nico Schottelius committed
128
removed on **python3.2** installation. You surely want to reinstall them:
129 130 131

  apt-get install -t wheezy openssh-server openssh-client

Nico Schottelius's avatar
Nico Schottelius committed
132 133 134
For older Debian versions, installing python 3.2 manually is required.


135 136 137 138 139 140 141 142 143 144 145 146 147 148 149
#### Fedora

For Fedora >= 15:

    yum install python3

#### FreeBSD

For the port:

    cd /usr/ports/lang/python32/ && make install clean

For the package:

    pkg_add -r python32
150

Daniel Roth's avatar
Daniel Roth committed
151 152 153 154 155 156 157 158 159 160
#### 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

Daniel Roth's avatar
Daniel Roth committed
161 162
#### Max OS X

Nico Schottelius's avatar
Nico Schottelius committed
163 164 165 166 167 168 169
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:
Daniel Roth's avatar
Daniel Roth committed
170 171

    port install python32
Daniel Roth's avatar
Daniel Roth committed
172
    ln -s /opt/local/bin/python3.2 /opt/local/bin/python3
Daniel Roth's avatar
Daniel Roth committed
173

174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189
#### From Source

For those operating systems not yet support 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.


190 191 192 193
### Get 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.
Nico Schottelius's avatar
Nico Schottelius committed
194 195 196 197 198 199
To install cdist, execute the following commands:

    git clone git://git.schottelius.org/cdist
    cd cdist
    export PATH=$PATH:$(pwd -P)/bin

200
    # If you want the manpages
Nico Schottelius's avatar
Nico Schottelius committed
201
    ./build man
Nico Schottelius's avatar
Nico Schottelius committed
202 203 204 205 206
    export MANPATH=$MANPATH:$(pwd -P)/doc/man


### Available versions

207
There are at least the following branches available:
Nico Schottelius's avatar
Nico Schottelius committed
208

Nico Schottelius's avatar
Nico Schottelius committed
209
 * Development: master
Nico Schottelius's avatar
Nico Schottelius committed
210
 * 2.0: Python rewrite of cdist core [stable branch]
Nico Schottelius's avatar
Nico Schottelius committed
211 212 213

Old versions:

Nico Schottelius's avatar
Nico Schottelius committed
214
 * 1.7: Bugfixes, cleanups, new type and explorer rename
Nico Schottelius's avatar
Nico Schottelius committed
215
 * 1.6: New types, cleaned up \_\_package* types, internal cleanup
216
 * 1.5: Focus on object orientation instead of global stage orientation
Nico Schottelius's avatar
Nico Schottelius committed
217
 * 1.4: Support for redefiniton of objects (if equal)
218
 * 1.3: Support for local and remote code execution (current stable)
Nico Schottelius's avatar
Nico Schottelius committed
219
 * 1.2: Dependencies supported
220
 * 1.1: \_\_file to \_\_file, \_\_directory, \_\_link migration
221
 * 1.0: First official release
Nico Schottelius's avatar
Nico Schottelius committed
222

223
Other branches may be available for features or bugfixes, but they
Nico Schottelius's avatar
Nico Schottelius committed
224 225 226 227 228
may vanish at any point. To select a specific branch use

    # Generic code
    git checkout -b <name> origin/<name>
    
Nico Schottelius's avatar
Nico Schottelius committed
229
    # Stay on a specific version
Nico Schottelius's avatar
Nico Schottelius committed
230
    version=2.0
Nico Schottelius's avatar
Nico Schottelius committed
231
    git checkout -b $version origin/$version
Nico Schottelius's avatar
Nico Schottelius committed
232

Nico Schottelius's avatar
Nico Schottelius committed
233 234
### Mirrors

Nico Schottelius's avatar
Nico Schottelius committed
235
 * git://github.com/telmich/cdist.git ([github](https://github.com/telmich/cdist))
Nico Schottelius's avatar
Nico Schottelius committed
236
 * git://git.code.sf.net/p/cdist/code ([sourceforge](https://sourceforge.net/p/cdist/code))
Nico Schottelius's avatar
Nico Schottelius committed
237

238
## Update
Nico Schottelius's avatar
Nico Schottelius committed
239 240 241 242 243 244

To upgrade cdist in the current branch use

    git pull

    # Also update the manpages
Nico Schottelius's avatar
Nico Schottelius committed
245
    ./build man
Nico Schottelius's avatar
Nico Schottelius committed
246 247
    export MANPATH=$MANPATH:$(pwd -P)/doc/man

248 249 250 251
If you stay on a version branche (i.e. 1.0, 1.1., ...), nothing should break.
The master branch on the other hand is the development branch and may not be
working, break your setup or eat the tree in your garden.

Nico Schottelius's avatar
Nico Schottelius committed
252 253
### Upgrading from 1.7 to 2.0

Nico Schottelius's avatar
Nico Schottelius committed
254 255 256
* Ensure python (>= 3.2) is installed on the server
* Use "cdist config host" instead of "cdist-deploy-to host"
* Use "cdist config -p host1 host2" instead of "cdist-mass-deploy"
257
* Use "cdist banner" for fun
Nico Schottelius's avatar
Nico Schottelius committed
258 259
* Use **\_\_object_fq** instead of **\_\_self** in manifests

Nico Schottelius's avatar
Nico Schottelius committed
260 261 262 263 264
### Upgrading from 1.6 to 1.7

* If you used the global explorer **hardware_type**, you need to change
  your code to use **machine** instead.

265 266 267 268 269 270 271 272
### Upgrading from 1.5 to 1.6

* If you used **\_\_package_apt --preseed**, you need to use the new
  type **\_\_debconf_set_selections** instead.
* The **\_\_package** types accepted either --state deinstalled or
  --state uninstaaled. Starting with 1.6, it was made consistently
  to --state removed.

273
### Upgrading from 1.3 to 1.5
274 275 276

No incompatiblities.

277 278 279 280
### Upgrading from 1.2 to 1.3

Rename **gencode** of every type to **gencode-remote**.

Nico Schottelius's avatar
Nico Schottelius committed
281 282 283 284
### Upgrading from 1.1 to 1.2

No incompatiblities.

285 286
### Upgrading from 1.0 to 1.1

287 288 289
In 1.1 the type **\_\_file** was split into **\_\_directory**, **\_\_file** and
**\_\_link**. The parameter **--type** was removed from **\_\_file**. Thus you
need to replace **\_\_file** calls in your manifests:
290

291 292 293
 * Remove --type from all \_\_file calls
 * If type was symlink, use \_\_link and --type symbolic
 * If type was directory, use \_\_directory
Nico Schottelius's avatar
Nico Schottelius committed
294 295 296 297 298 299 300


## Support

### IRC

You can join the development ***IRC channel***
Chris Lamb's avatar
Chris Lamb committed
301
[#cstar on irc.freenode.net](irc://irc.freenode.org/#cstar).
Nico Schottelius's avatar
Nico Schottelius committed
302 303 304 305 306 307

### Mailing list

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

Nico Schottelius's avatar
Nico Schottelius committed
308 309 310 311 312 313 314
### Linkedin

If you have an account
at [Linked in](http://www.linkedin.com/),
you can join the
[cdist group](http://www.linkedin.com/groups/cdist-configuration-management-3952797).

315
### Commercial support
Nico Schottelius's avatar
Nico Schottelius committed
316 317 318 319

You can request commercial support for cdist from
[my company](http://firma.schottelius.org/english/).

Nico Schottelius's avatar
Nico Schottelius committed
320 321 322 323 324 325 326 327 328 329
## 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's avatar
Nico Schottelius committed
330
### Nico Schottelius, Systems Group ETH Zurich, local.ch and privately
Nico Schottelius's avatar
Nico Schottelius committed
331 332 333 334 335 336 337

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)
338
 * [nss-pam-ldapd](http://arthurdejong.org/nss-pam-ldapd/) (authentication)
Nico Schottelius's avatar
Nico Schottelius committed
339 340
 * [ircd-hybrid](http://www.ircd-hybrid.org/) (chat)
 * [stunnel](http://stunnel.mirt.net/) (SSL tunnel)
Nico Schottelius's avatar
+urls  
Nico Schottelius committed
341 342 343
 * [mercurial-server](http://www.lshift.net/mercurial-server.html) (version control)
 * [xfce](http://www.xfce.org/) (lightweight desktop environment)
 * [slim](http://slim.berlios.de/) (graphical login manager for X11)
Nico Schottelius's avatar
Nico Schottelius committed
344

345
with cdist on more than **60** production machines of the
Nico Schottelius's avatar
Nico Schottelius committed
346
[Systems Group](http://www.systems.ethz.ch) at the
Nico Schottelius's avatar
Nico Schottelius committed
347
[ETH Zurich](http://www.ethz.ch) as well at home.
Steven Armstrong's avatar
Steven Armstrong committed
348 349 350 351 352

### Steven Armstrong, CBRG ETH Zurich

The CBRG is managing most of their compute clusters with cdist.

Nico Schottelius's avatar
Nico Schottelius committed
353
[[!tag cdist unix]]