From c223a4ac5ca5d88597e7b7784ef4b93ac614896d Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Thu, 28 Oct 2010 21:13:57 +0200 Subject: [PATCH] move around documentation Signed-off-by: Nico Schottelius --- Makefile | 6 ++ README | 171 ----------------------------------- TODO | 10 +- bin/cdist-build | 1 - bin/cdist-deploy-to | 2 +- doc/internal/puppet-analysis | 66 ++++++++++++++ doc/man/cdist.text | 106 ++++++++++++++++++++++ 7 files changed, 187 insertions(+), 175 deletions(-) create mode 100644 doc/internal/puppet-analysis diff --git a/Makefile b/Makefile index 1dd8eb9b..729474c9 100644 --- a/Makefile +++ b/Makefile @@ -1,3 +1,9 @@ +PREFIX=/usr +BINDIR=$(PREFIX}/bin + +install: + cp bin/* $(BINDIR) + sync: .rsync lyni@tablett:cdist .rsync nicosc@free.ethz.ch:cdist diff --git a/README b/README index 0a571a8c..ddcefddb 100644 --- a/README +++ b/README @@ -46,174 +46,3 @@ and is equipped with manpages. ## 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" - - - diff --git a/TODO b/TODO index d710fbd9..63a33b76 100644 --- a/TODO +++ b/TODO @@ -1,2 +1,8 @@ -- find out where I left work :-) -- create real todo +- doc: + - readme (cleanup, define) + - cdist manpage (main manpage) + - create todos from doc/internal/puppet-analysis +- cdist-deply-to + - sync conf/{lib/,modules,host/$name} +- cdist-build-explorer| ssh localhost +- diff --git a/bin/cdist-build b/bin/cdist-build index 3290886b..a26b9458 100755 --- a/bin/cdist-build +++ b/bin/cdist-build @@ -26,7 +26,6 @@ [ $# -eq 1 ] || __cdist_usage "target" set -e -set -x . cdist-preprocess "$1" . cdist-compile "$1" diff --git a/bin/cdist-deploy-to b/bin/cdist-deploy-to index e369c4e8..c1a8c835 100755 --- a/bin/cdist-deploy-to +++ b/bin/cdist-deploy-to @@ -1,4 +1,4 @@ -!/bin/sh +#!/bin/sh # # 2010 Nico Schottelius (nico-cdist at schottelius.org) # diff --git a/doc/internal/puppet-analysis b/doc/internal/puppet-analysis new file mode 100644 index 00000000..6d10e18e --- /dev/null +++ b/doc/internal/puppet-analysis @@ -0,0 +1,66 @@ +## 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 + + diff --git a/doc/man/cdist.text b/doc/man/cdist.text index 6fba8bea..c1b6667b 100644 --- a/doc/man/cdist.text +++ b/doc/man/cdist.text @@ -31,3 +31,109 @@ COPYING ------- Copyright \(C) 2010 Nico Schottelius. Free use of this software is granted under the terms of the GNU General Public License version 3 (GPLv3). + +-------------------------------------------------------------------------------- + + +## 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*** + + +-------------------------------------------------------------------------------- +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" + + +