From 88d9cf13de2e94f96efee0329962206a654c85c6 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Mon, 1 Nov 2010 16:19:54 +0100 Subject: [PATCH] cleanup cdist manpage, add todos at various positions Signed-off-by: Nico Schottelius --- TODO | 17 ++++++ doc/internal/config-layout | 9 +++ doc/man/cdist-design.text | 35 +++++++++++ doc/man/cdist-language.text | 27 +++++++++ doc/man/cdist-quickstart.text | 5 ++ doc/man/cdist.text | 110 +--------------------------------- 6 files changed, 96 insertions(+), 107 deletions(-) create mode 100644 doc/internal/config-layout create mode 100644 doc/man/cdist-quickstart.text diff --git a/TODO b/TODO index e156fe77..e7841d03 100644 --- a/TODO +++ b/TODO @@ -1,5 +1,8 @@ - doc: - cdist manpage (main manpage) + - cleanup following man + their tree: + - cdist.text + - cdist-design.text - add terminology - define entry point - define modules / mix with library? @@ -43,6 +46,20 @@ - disconnected clients with "cache" - release first public version, which includes at least: - manpages + - only do necessary work + - install packages only if not existent + - copy file only if different + +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 + + -------------------------------------------------------------------------------- Later: diff --git a/doc/internal/config-layout b/doc/internal/config-layout new file mode 100644 index 00000000..a4f62a2c --- /dev/null +++ b/doc/internal/config-layout @@ -0,0 +1,9 @@ +On the server: + +conf/hosts/init $hostname + => will be called by $whatever + => may source other files + => $__hosts_dir can be used to source other scripts + +Cached client: + Has generated file, which will be (re-)applied diff --git a/doc/man/cdist-design.text b/doc/man/cdist-design.text index c879978a..cdb0dcbd 100644 --- a/doc/man/cdist-design.text +++ b/doc/man/cdist-design.text @@ -36,6 +36,41 @@ When using cdist with the pull principle (configuration triggered by client): cdist-deploy-to(1) % server: see above -------------------------------------------------------------------------------- + +MERGE INTO ABOVE..... +## 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. + + - 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, + =>=>>>>>>>>>>>>>>>> via cconfig + + SEE ALSO -------- cdist(7), website: http://www.nico.schottelius.org/cdist/[] diff --git a/doc/man/cdist-language.text b/doc/man/cdist-language.text index 613a8fd3..d03afd20 100644 --- a/doc/man/cdist-language.text +++ b/doc/man/cdist-language.text @@ -29,6 +29,33 @@ The three stages are used to seperate configurations: - the library is shipped with cdist, but can be extendet locally + - 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? + + - matching on explored items, not only on host name? + - match function in host? [optional] + - explorer ran before! + +- document exported variables! + use __ prefix instead of __cdist (shorter writing, __ is defined as sytem anyway) + +- library vs. modules? + +Requirements: + It MUST be incredible easy/dumb to add new types. + => growable default types + + SEE ALSO -------- diff --git a/doc/man/cdist-quickstart.text b/doc/man/cdist-quickstart.text new file mode 100644 index 00000000..0d447a59 --- /dev/null +++ b/doc/man/cdist-quickstart.text @@ -0,0 +1,5 @@ +## How to use cdist? + + 0. Create a host specification (/etc/cdist/hosts/**hostname**) + 0. Add functionalilty to add + 0. Run ***cdist-apply*** diff --git a/doc/man/cdist.text b/doc/man/cdist.text index b1b5fc2f..efc7433d 100644 --- a/doc/man/cdist.text +++ b/doc/man/cdist.text @@ -20,120 +20,16 @@ internal configuration representation (cconfig), which again is used to generate an executable, which is run on the client (see cdist-language(7), cdist-design(7)). +To get your fingers dirty with cdist very quick, have +a look at cdist-quickstart(7). SEE ALSO -------- -cdist-deploy-to(1), website: http://www.nico.schottelius.org/cdist/[] +Website: http://www.nico.schottelius.org/cdist/[] 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" - - -