make readme readme

Signed-off-by: Nico Schottelius <nico@kr.ethz.ch>
This commit is contained in:
Nico Schottelius 2010-10-28 21:10:51 +02:00
parent 070a1d6e0c
commit 3bbf032b41
2 changed files with 219 additions and 220 deletions

1
README
View file

@ -1 +0,0 @@
cdist.mdwn

219
README Normal file
View file

@ -0,0 +1,219 @@
## Introduction
cdist configures your system. It is similar to
[cfengine](http://www.cfengine.org/) and [puppet](http://www.puppetlabs.com/).
It is inspired by both of those tools:
* Try to redo the great power you get
* But leave out the bugs you also got
And cdist is UNIX:
It's designed to reuse existing tools,
does not require high level scripting language interpreters
and is equipped with manpages.
### Architecture
* KISS (keep it simple and stupid)
* Allow very easy extension of cdist (creating own types for instance)
* Push (server pushes configuration) and Pull (client retrieves config) supported
* User defines configuration in shell scripts using cdist functions
* Cdist generates internal configuration (cconfig style) and afterwards applies configuration
## Requirements
### Server
* A posix like shell
* SSH-Client (for push architecture)
* SSH-Server (for pull architecture)
### Client
* A posix like shell
* SSH-Client (for pull architecture)
* SSH-Server (for push architecture)
## How to get cdist
git clone git://git.schottelius.org/cdist
## How to install cdist
make install
## How to use cdist
man cdist
--------------------------------------------------------------------------------
## How cdist works
### Exploring your system
cdist analyses the system to apply the configuration on and
selects the right backends. You can use ***cdist-explore*** to
the results of the explore functions.
### Applying the configuration
cdist looks for the configuration to apply on the local host
and applies it using ***cdist-apply***.
### Managing many hosts
Whereas ***cdist-apply*** manages one host, ***cdist-deploy***
applies the configuration on enabled hosts.
## How to use cdist?
0. Create a host specification (/etc/cdist/hosts/**hostname**)
0. Add functionalilty to add
0. Run ***cdist-apply***
## What do I need [from puppet?]
### Abstraction of package managers
I don't want to care about apt, rpm, yum, pacman, etc. I just
want to ensure, some package exists or does not exist.
### Common tasks already done
- [LIBRARY] All the helper types like
- file
- ssh_keys
- package
- service
- user
### PORTABILITY
- [PORTABILITY] clients for every unix
- mostly ruby + facter in puppet
### Other
- Modules: Nice to put stuff together
- and reuse
- [CONDITIONS] facter is cool
- the DSL
- with many bugs
- templates
- Client/Server approach is nice to have
- Clients only get the part of the documentation, that's
relevant to them
- detect impossible/unsafe things:
- creating a file twice
- installing and removing a package
- and report location of occurence
- parse afterwards?
--------------------------------------------------------------------------------
what is puppet? [FOR ME]
A configuration deployment assistant,
a DSL that allows you define the objectives.
A webserver with fileserver capabilities.
A client based scheduled polling infrastructure.
--------------------------------------------------------------------------------
What do I miss from puppet?
- speed
- elegance
- clean design
- documentation
- the "no surprise" factor
- easy to use "data memory" (i.e. external ressources)
- easy integration into installation process
- copy identity to master
- multi master setups
- development configurations / tests
- editing of configuration files
- similar to cfengine
- replace bug squasher with bug avoidance
- qmail did not need one either
- push infrastructure
- real / meaningful error messages
--------------------------------------------------------------------------------
Simple stuff done by Unix[notm]
- DSL: Shell!
- gives if, else and EVEN elsif for free!
- and case
- and and and
- and there's no os (solaris doesn't count) without a usable /bin/sh
- cdist defines what you can use
- you _can_ use os specific stuff
- but it's ugly and you shoot into your own foot
- "manifests" (use the same name here?) will be run/sourced
- inheritance possible via sourcing
- cdist-lib always preloaded
- library == functions?
- version control via git
- file distribution via ssh
- authentication via ssh
- dumb clients, similar to manifest compile in puppet
- clients just execute commands
- dependencies via make?
- how to ensure sigletons / conflicting definitions?
file { "/a":
ensure => present,
file { "/a":
ensure => absent,
- matching on explored items, not only on host name?
- match function in host? [optional]
- file source:
- relative to specification
- or absolute
--------------------------------------------------------------------------------
Implementation
"cdist-server"
-> called by cron?
-> no need to reimplement scheduling
"cdist-explore" (facter replacement)
-> running on the client
--------------------------------------------------------------------------------
Requirements:
It MUST be incredible easy/dumb to add new types.
=> growable default types
--------------------------------------------------------------------------------
## TO DOC
Before initial release, document:
- how to add package backends
- how to write a minimal host manifest
- create library with all functions (and their parameters)
- cdist_package
- cdist_file
- cdist_dir
- only do necessary work
- install packages only if not existent
- copy file only if different
- how to write a module
- module function autoloading via *.sh
- module "manifest"?
- create functions in *.sh
- name functions "modulename_function"
module hellow
function kitty
=> hellow_kitty
- you are advised (not forced) to put files
to a subdirectory named "files"

View file

@ -1,219 +0,0 @@
## Introduction
cdist configures your system. It is similar to
[cfengine](http://www.cfengine.org/) and [puppet](http://www.puppetlabs.com/).
It is inspired by both of those tools:
* Try to redo the great power you get
* But leave out the bugs you also got
And cdist is UNIX:
It's designed to reuse existing tools,
does not require high level scripting language interpreters
and is equipped with manpages.
### Architecture
* KISS (keep it simple and stupid)
* Allow very easy extension of cdist (creating own types for instance)
* Push (server pushes configuration) and Pull (client retrieves config) supported
* User defines configuration in shell scripts using cdist functions
* Cdist generates internal configuration (cconfig style) and afterwards applies configuration
## Requirements
### Server
* A posix like shell
* SSH-Client (for push architecture)
* SSH-Server (for pull architecture)
### Client
* A posix like shell
* SSH-Client (for pull architecture)
* SSH-Server (for push architecture)
## How to get cdist
git clone git://git.schottelius.org/cdist
## How to install cdist
make install
## How to use cdist
man cdist
--------------------------------------------------------------------------------
## How cdist works
### Exploring your system
cdist analyses the system to apply the configuration on and
selects the right backends. You can use ***cdist-explore*** to
the results of the explore functions.
### Applying the configuration
cdist looks for the configuration to apply on the local host
and applies it using ***cdist-apply***.
### Managing many hosts
Whereas ***cdist-apply*** manages one host, ***cdist-deploy***
applies the configuration on enabled hosts.
## How to use cdist?
0. Create a host specification (/etc/cdist/hosts/**hostname**)
0. Add functionalilty to add
0. Run ***cdist-apply***
## What do I need [from puppet?]
### Abstraction of package managers
I don't want to care about apt, rpm, yum, pacman, etc. I just
want to ensure, some package exists or does not exist.
### Common tasks already done
- [LIBRARY] All the helper types like
- file
- ssh_keys
- package
- service
- user
### PORTABILITY
- [PORTABILITY] clients for every unix
- mostly ruby + facter in puppet
### Other
- Modules: Nice to put stuff together
- and reuse
- [CONDITIONS] facter is cool
- the DSL
- with many bugs
- templates
- Client/Server approach is nice to have
- Clients only get the part of the documentation, that's
relevant to them
- detect impossible/unsafe things:
- creating a file twice
- installing and removing a package
- and report location of occurence
- parse afterwards?
--------------------------------------------------------------------------------
what is puppet? [FOR ME]
A configuration deployment assistant,
a DSL that allows you define the objectives.
A webserver with fileserver capabilities.
A client based scheduled polling infrastructure.
--------------------------------------------------------------------------------
What do I miss from puppet?
- speed
- elegance
- clean design
- documentation
- the "no surprise" factor
- easy to use "data memory" (i.e. external ressources)
- easy integration into installation process
- copy identity to master
- multi master setups
- development configurations / tests
- editing of configuration files
- similar to cfengine
- replace bug squasher with bug avoidance
- qmail did not need one either
- push infrastructure
- real / meaningful error messages
--------------------------------------------------------------------------------
Simple stuff done by Unix[notm]
- DSL: Shell!
- gives if, else and EVEN elsif for free!
- and case
- and and and
- and there's no os (solaris doesn't count) without a usable /bin/sh
- cdist defines what you can use
- you _can_ use os specific stuff
- but it's ugly and you shoot into your own foot
- "manifests" (use the same name here?) will be run/sourced
- inheritance possible via sourcing
- cdist-lib always preloaded
- library == functions?
- version control via git
- file distribution via ssh
- authentication via ssh
- dumb clients, similar to manifest compile in puppet
- clients just execute commands
- dependencies via make?
- how to ensure sigletons / conflicting definitions?
file { "/a":
ensure => present,
file { "/a":
ensure => absent,
- matching on explored items, not only on host name?
- match function in host? [optional]
- file source:
- relative to specification
- or absolute
--------------------------------------------------------------------------------
Implementation
"cdist-server"
-> called by cron?
-> no need to reimplement scheduling
"cdist-explore" (facter replacement)
-> running on the client
--------------------------------------------------------------------------------
Requirements:
It MUST be incredible easy/dumb to add new types.
=> growable default types
--------------------------------------------------------------------------------
## TO DOC
Before initial release, document:
- how to add package backends
- how to write a minimal host manifest
- create library with all functions (and their parameters)
- cdist_package
- cdist_file
- cdist_dir
- only do necessary work
- install packages only if not existent
- copy file only if different
- how to write a module
- module function autoloading via *.sh
- module "manifest"?
- create functions in *.sh
- name functions "modulename_function"
module hellow
function kitty
=> hellow_kitty
- you are advised (not forced) to put files
to a subdirectory named "files"