From 7a4ab2efd8ea6e42a46177c85220ae0ca6f8804a Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Wed, 9 Mar 2011 08:53:19 +0100 Subject: [PATCH 01/11] integrate the first type manpage into cdist Signed-off-by: Nico Schottelius --- Makefile | 13 ++- doc/changelog | 2 +- doc/man/.gitignore | 1 + doc/man/cdist-type-listing.text.sh | 160 ++++------------------------- 4 files changed, 34 insertions(+), 142 deletions(-) mode change 100644 => 100755 doc/man/cdist-type-listing.text.sh diff --git a/Makefile b/Makefile index e003c0c6..5d099260 100644 --- a/Makefile +++ b/Makefile @@ -16,6 +16,8 @@ MANSRC=$(MANDIR)/cdist-config-layout.text \ $(MANDIR)/cdist-stages.text \ $(MANDIR)/cdist-terms.text \ +MANGENERATED=$(MANDIR)/cdist-type-listing.text + MANSRC=$(MANDIR)/cdist.text \ $(MANDIR)/cdist-bin-transfer.text \ $(MANDIR)/cdist-deploy-to.text \ @@ -23,7 +25,7 @@ MANSRC=$(MANDIR)/cdist.text \ $(MANDIR)/cdist-stages.text \ $(MANDIR)/cdist-type.text \ $(MANDIR)/cdist-type-template.text \ - $(MANDIR)/cdist-type__file.text \ + $(MANDIR)/cdist-type__file.text \ ################################################################################ @@ -43,11 +45,16 @@ all: man: doc/man/.marker -doc/man/.marker: $(MANSRC) - for mansrc in $(MANSRC); do $(A2X) $$mansrc; done +doc/man/.marker: $(MANSRC) $(MANGENERATED) + for mansrc in $^; do $(A2X) $$mansrc; done for manpage in $(MANDIR)/*.[1-9]; do cat=$${manpage##*.}; mandir=$(MANDIR)/man$$cat; mkdir -p $$mandir; mv $$manpage $$mandir; done touch $@ +# Only depends on cdist-type__*.text in reality +$(MANDIR)/cdist-type-listing.text: $(MANSRC) $(MANDIR)/cdist-type-listing.text.sh + $(MANDIR)/cdist-type-listing.text.sh + + clean: rm -rf doc/man/*.html doc/man/*.[1-9] doc/man/man[1-9] diff --git a/doc/changelog b/doc/changelog index b0087c36..528b7e86 100644 --- a/doc/changelog +++ b/doc/changelog @@ -1,5 +1,5 @@ 1.0.2: upcoming - * Add manpages: cdist-type + * Add manpages: cdist-type, cdist-type__file * Make doc/man/ usable as MANPATH entry 1.0.1: 2011-03-08 diff --git a/doc/man/.gitignore b/doc/man/.gitignore index 22d0a62d..299485e8 100644 --- a/doc/man/.gitignore +++ b/doc/man/.gitignore @@ -1,3 +1,4 @@ cdist.7 *.html cdist-design.7 +cdist-type-listing.text diff --git a/doc/man/cdist-type-listing.text.sh b/doc/man/cdist-type-listing.text.sh old mode 100644 new mode 100755 index 78c04a43..d1da1477 --- a/doc/man/cdist-type-listing.text.sh +++ b/doc/man/cdist-type-listing.text.sh @@ -30,9 +30,11 @@ __cdist_abs_myname="$__cdist_abs_mydir/$__cdist_myname" filename="${__cdist_myname%.sh}" dest="$__cdist_abs_mydir/$filename" -exit 0 +cd "$__cdist_abs_mydir" -cat << eof > "$dest" +exec > "$dest" + +cat << eof cdist-type-listing(7) ===================== Nico Schottelius @@ -50,150 +52,32 @@ Types that are included in cdist $(git describe). DESCRIPTION ----------- -Types are the main component of cdist and define functionality. If you -use cdist, you'll write a type for every functionality you would like -to use. +The following types are available: +eof +for type in cdist-type__*.text; do + name_1="${type#cdist-type}" + name_2="${name_1%.text}" -HOW TO USE A TYPE ------------------ -You can use types from the initial manifest or the type manifest like a -normal command: + name="$name_2" + echo "- $name" +done --------------------------------------------------------------------------------- -# Creates empty file /etc/cdist-configured -__file /etc/cdist-configured --type file - -# Ensure tree is installed -__package tree --state installed --------------------------------------------------------------------------------- - -Internally cdist-type-emulator(1) will be called from cdist-manifest-run(1) to -save the given parameters into a cconfig database, so they can be accessed by -the manifest and gencode scripts of the type (see below). - - -HOW TO WRITE A NEW TYPE ------------------------ -A type consists of - -- parameter (optional) -- manifest (optional) -- explorer (optional) -- gencode (optional) - -Types are stored below conf/type/. Their name should always be prefixed with -two underscores (__) to prevent collisions with other binaries in $PATH. - -To begin a new type from a template, execute "cdist-type-template __NAME" -and cd conf/type/__NAME. - - -DEFINING PARAMETERS -------------------- -Every type consists of optional and required parameters, which must -be created in a newline seperated file in parameters/required and -parameters/optional. If either or both missing, the type will have -no required, no optional or no parameters at all. - -Example: --------------------------------------------------------------------------------- -echo servername >> conf/type/__nginx_vhost/parameter/required -echo logdirectory >> conf/type/__nginx_vhost/parameter/optional --------------------------------------------------------------------------------- - - -WRITING THE MANIFEST --------------------- -In the manifest of a type you can use other types, so your type extends -their functionality. A good example is the __package type, which in -a shortened version looks like this: - --------------------------------------------------------------------------------- -os="$(cat "$__global/explorer/os")" -case "$os" in - archlinux) type="pacman" ;; - debian|ubuntu) type="apt" ;; - gentoo) type="emerge" ;; - *) - echo "Don't know how to manage packages on: $os" >&2 - exit 1 - ;; -esac - -__package_$type "$@" --------------------------------------------------------------------------------- - -As you can see, the type can reference different environment variables, -which are documented in cdist-environment-variables(7). - -Always ensure the manifest is executable, otherwise cdist will not be able -to execute it. - - -THE TYPE EXPLORERS ------------------- -If a type needs to explore specific details, it can provide type specific -explorers, which will be executed on the target for every created object. - -The explorers are stored under the "explorer" directory below the type. -It could for instance contain code to check the md5sum of a file on the -client, like this (shortened version from real type __file): - --------------------------------------------------------------------------------- -if [ -f "$__object/parameter/destination" ]; then - destination="$(cat "$__object/parameter/destination")" -else - destination="/$__object_id" -fi - -if [ -e "$destination" ]; then - md5sum < "$destination" -fi --------------------------------------------------------------------------------- - - -WRITING THE GENCODE SCRIPT --------------------------- -The gencode script can make use of the parameters, the global explorers -and the type specific explorers. The output (stdout) of this script is -saved by cdist and will be executed on the target. - -If the gencode script encounters an error, it should print diagnostic -messages to stderr and exit non-zero. If you need to debug the gencode -script, you can write to stderr: - --------------------------------------------------------------------------------- -# Debug output to stderr -echo "My fancy debug line" >&2 - -# Output to be saved by cdist for execution on the target -echo "touch /etc/cdist-configured" --------------------------------------------------------------------------------- - - -HINTS FOR TYPEWRITERS ----------------------- -It must be assumed that the target is pretty dumb and thus does not have high -level tools like ruby installed. If a type requires specific tools to be present -on the target, there must be another type that provides this tool and the first -type should create an object of the specific type. - - -HOW TO INCLUDE A TYPE INTO UPSTREAM CDIST ------------------------------------------ -If you think your type may be useful for others, ensure it works with the -current master branch of cdist and submit the git url containing the type for -inclusion to the mailinglist **cdist at cdist -- at -- l.schottelius.org**. - -Ensure a corresponding manpage named cdist-type__NAME is included. +cat << eof SEE ALSO -------- -- cdist-manifest-run(1) -- cdist-stages(7) +- cdist-type(7) +eof +for type in cdist-type__*.text; do + name_2="${type%.text}" + name="$name_2" + echo "- ${name}(7)" +done + +cat < Date: Wed, 9 Mar 2011 08:54:52 +0100 Subject: [PATCH 02/11] lesstodo and add pointer to type manpages Signed-off-by: Nico Schottelius --- doc/dev/todo/niconext | 2 +- doc/man/cdist-type.text | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/dev/todo/niconext b/doc/dev/todo/niconext index 636cd561..3f7c91d5 100644 --- a/doc/dev/todo/niconext +++ b/doc/dev/todo/niconext @@ -1,4 +1,4 @@ Documentation cleanup - document environment variables - - Reference all types somewhere (on the webpage?) - how to debug explorer + => 1.0.2 diff --git a/doc/man/cdist-type.text b/doc/man/cdist-type.text index 3c7a1317..b5097a5c 100644 --- a/doc/man/cdist-type.text +++ b/doc/man/cdist-type.text @@ -37,6 +37,8 @@ Internally cdist-type-emulator(1) will be called from cdist-manifest-run(1) to save the given parameters into a cconfig database, so they can be accessed by the manifest and gencode scripts of the type (see below). +A list of supported types can be found in the cdist-type-listing(7) manpage. + HOW TO WRITE A NEW TYPE ----------------------- From 75d8abc339f56b3427207e35088627249975d232 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Wed, 9 Mar 2011 08:56:31 +0100 Subject: [PATCH 03/11] remove generated manpages Signed-off-by: Nico Schottelius --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 5d099260..6a880c48 100644 --- a/Makefile +++ b/Makefile @@ -56,7 +56,7 @@ $(MANDIR)/cdist-type-listing.text: $(MANSRC) $(MANDIR)/cdist-type-listing.text.s clean: - rm -rf doc/man/*.html doc/man/*.[1-9] doc/man/man[1-9] + rm -rf doc/man/*.html doc/man/*.[1-9] doc/man/man[1-9] $(MANGENERATED) ################################################################################ # Developer targets From 1048c42c6dde27abe41ea0b790aaf745981e74c5 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Wed, 9 Mar 2011 09:15:34 +0100 Subject: [PATCH 04/11] merge cdist-config-layout into cdist-reference Signed-off-by: Nico Schottelius --- doc/dev/todo/niconext | 1 + doc/man/cdist.text | 11 +- doc/man/to_check/cdist-config-layout.text | 108 ---------- .../to_check/cdist-environment-variables.text | 197 +++++++++++++++++- 4 files changed, 193 insertions(+), 124 deletions(-) delete mode 100644 doc/man/to_check/cdist-config-layout.text diff --git a/doc/dev/todo/niconext b/doc/dev/todo/niconext index 3f7c91d5..f7acbe88 100644 --- a/doc/dev/todo/niconext +++ b/doc/dev/todo/niconext @@ -1,4 +1,5 @@ Documentation cleanup - document environment variables + - and merge with config-layout! - how to debug explorer => 1.0.2 diff --git a/doc/man/cdist.text b/doc/man/cdist.text index b6fd808b..570b6b95 100644 --- a/doc/man/cdist.text +++ b/doc/man/cdist.text @@ -29,12 +29,11 @@ pull mechanism (client requests configuration). SEE ALSO -------- -Website: http://www.nico.schottelius.org/cdist/[], -cdist-deploy-to(1), -cdist-manifest(7), -cdist-quickstart(1), -cdist-type(7), -cdist-type-inclusion(7) +- Website: http://www.nico.schottelius.org/cdist/[] +- cdist-deploy-to(1) +- cdist-manifest(7) +- cdist-quickstart(1) +- cdist-type(7) COPYING diff --git a/doc/man/to_check/cdist-config-layout.text b/doc/man/to_check/cdist-config-layout.text deleted file mode 100644 index d6be10df..00000000 --- a/doc/man/to_check/cdist-config-layout.text +++ /dev/null @@ -1,108 +0,0 @@ -cdist-config-layout(7) -====================== -Nico Schottelius - - -NAME ----- -cdist-config-layout - Usage of paths in cdist - - -DESCRIPTION ------------ -If not specified otherwise, all paths are relative to the configuration -directory, which is normally /etc/cdist (but can be changed using environment -variables, see cdist-environment(7)). - -- conf_dir/: - Contains the (static) configuration like manifests, types and - explorers. - -- conf_dir/manifest/init: - This is the central entry point used by cdist-manifest-init(1). - It is an executable (+x bit set) shell script that can use - values from the explorers to decide which configuration to create - for the specified target host. - - It should be primary used to define mapping from configurations to hosts. - -- conf_dir/manifest/*: - All other files in this directory are not directly used by Cdist, but you - can seperate configuration mappings, if you have a lot of code in the - manifest/init file. This may also be very helpful to have different admins - maintain different groups of hosts. - -- conf_dir/explorer/ - Contains explorers to be run on the target hosts, see cdist-explorers(7). - -- conf_dir/type/ - Contains all available types, which are used to provide - some kind of functionality. See cdist-stages(7). - -- conf_dir/type//manifest: - Used to generate additional objects from a type. - See cdist-stages(7), cdist-types(7). - -- conf_dir/type//gencode: - Used to generate code to be executed on the client. - See cdist-types(7). - -- conf_dir/type//parameters/required: - Parameters required by type, \n seperated list. - See cdist-types(7). - -- conf_dir/type//parameters/optional: - Parameters optionally accepted by type, \n seperated list. - See cdist-types(7). - -- conf_dir/type//explorer: - Location of the type specific explorers. - See cdist-explorers(7). - -- out_dir/ - This directory contains output of cdist and is mirrored into the - cache after a successful run. This directory may be placed below - the tmpdir or at any other location and is also available on the - target. - -- out_dir/explorer: - Output of general explorers. - -- out_dir/object: - Objects created for the host. - -- out_dir/object//explorers: - Output of type specific explorers, per object. - -- tmp_dir: Temporary storage - A tempdir and a tempfile is provided by cdist-config(1), which - will be removed when the scripts ends automatically. - - -FUTURE ------- -The following functionality may be implemented in one of the next releases: - -- cache_dir/ - The cache contains the out_dir from previous runs, which - may also be used in types to gather information about other hosts - (like ssh-keys). - -- cache_dir/host/: - Contains the last out_dir of the specific host. - - -AUTHOR ------- -Nico Schottelius - - -RESOURCES ---------- -Main web site: http://www.nico.schottelius.org/cdist/[] - - -COPYING -------- -Copyright \(C) 2010-2011 Nico Schottelius. Free use of this software is -granted under the terms of the GNU General Public License version 3 (GPLv3). diff --git a/doc/man/to_check/cdist-environment-variables.text b/doc/man/to_check/cdist-environment-variables.text index c91a2ae0..f39366f0 100644 --- a/doc/man/to_check/cdist-environment-variables.text +++ b/doc/man/to_check/cdist-environment-variables.text @@ -1,14 +1,191 @@ -Update on env: +cdist-reference(7) +================== +Nico Schottelius - general explorer: __explorer - initial manifest: __manifest, __global - type manifests __object, __object_id, __global - type explorers: __object, __object_id, __type_explorers, __global - type codegen: __object, __object_id, __global - type code: - +NAME +---- +cdist-reference - Variables, paths and types offered by cdist -- __object: Path to the object that we are working on -- __object_id: type unique object id -- __global: contains global information (see cdist-env +DESCRIPTION +----------- +Various scripts which are not in the core need information on how +to find information. This manpage summarises the available environment +variables and clearifies with part may access with variables. +PATHS +----- + + +-------------------------------------------------------------------------------- +cdist-config-layout(7) +====================== +Nico Schottelius + + +NAME +---- +cdist-config-layout - Usage of paths in cdist + + +DESCRIPTION +----------- +If not specified otherwise, all paths are relative to the configuration +directory, which is normally /etc/cdist (but can be changed using environment +variables, see cdist-environment(7)). + +- conf_dir/: + Contains the (static) configuration like manifests, types and + explorers. + +- conf_dir/manifest/init: + This is the central entry point used by cdist-manifest-init(1). + It is an executable (+x bit set) shell script that can use + values from the explorers to decide which configuration to create + for the specified target host. + + It should be primary used to define mapping from configurations to hosts. + +- conf_dir/manifest/*: + All other files in this directory are not directly used by Cdist, but you + can seperate configuration mappings, if you have a lot of code in the + manifest/init file. This may also be very helpful to have different admins + maintain different groups of hosts. + +- conf_dir/explorer/ + Contains explorers to be run on the target hosts, see cdist-explorers(7). + +- conf_dir/type/ + Contains all available types, which are used to provide + some kind of functionality. See cdist-stages(7). + +- conf_dir/type//manifest: + Used to generate additional objects from a type. + See cdist-stages(7), cdist-types(7). + +- conf_dir/type//gencode: + Used to generate code to be executed on the client. + See cdist-types(7). + +- conf_dir/type//parameters/required: + Parameters required by type, \n seperated list. + See cdist-types(7). + +- conf_dir/type//parameters/optional: + Parameters optionally accepted by type, \n seperated list. + See cdist-types(7). + +- conf_dir/type//explorer: + Location of the type specific explorers. + See cdist-explorers(7). + +- out_dir/ + This directory contains output of cdist and is mirrored into the + cache after a successful run. This directory may be placed below + the tmpdir or at any other location and is also available on the + target. + +- out_dir/explorer: + Output of general explorers. + +- out_dir/object: + Objects created for the host. + +- out_dir/object//explorers: + Output of type specific explorers, per object. + +- tmp_dir: Temporary storage + A tempdir and a tempfile is provided by cdist-config(1), which + will be removed when the scripts ends automatically. + + +FUTURE +------ +The following functionality may be implemented in one of the next releases: + +- cache_dir/ + The cache contains the out_dir from previous runs, which + may also be used in types to gather information about other hosts + (like ssh-keys). + +- cache_dir/host/: + Contains the last out_dir of the specific host. + + +AUTHOR +------ +Nico Schottelius + + +RESOURCES +--------- +Main web site: http://www.nico.schottelius.org/cdist/[] + + +COPYING +------- +Copyright \(C) 2010-2011 Nico Schottelius. Free use of this software is +granted under the terms of the GNU General Public License version 3 (GPLv3). +-------------------------------------------------------------------------------- + + + +VARIABLES +--------- +__explorer:: + Directory that contains all explorers +__manifest:: + Directory that contains the initial manifest +__global:: + Directory that contains generic output like explorer +__object:: + Directory that contains the current object +__object_id:: + The type unique object id +__type_explorers:: + Directory that contains the type explorers + + +EXPLORER +-------- +- __explorer + + +INITIAL MANIFEST +---------------- +- __manifest +- __global + + +TYPE MANIFEST +------------- +- __object +- __object_id +- __global + + +TYPE EXPLORER +------------- +- __object +- __object_id +- __type_explorers +- __global + + +TYPE CODEGEN +------------ +- __object +- __object_id +- __global + + + +SEE ALSO +-------- +- cdist(7) + + +COPYING +------- +Copyright \(C) 2011 Nico Schottelius. Free use of this software is +granted under the terms of the GNU General Public License version 3 (GPLv3). From ef761b73df0cbafd6fdc039b427aae9815181283 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Wed, 9 Mar 2011 09:34:53 +0100 Subject: [PATCH 05/11] finish first version of cdist-reference Signed-off-by: Nico Schottelius --- Makefile | 1 + doc/man/cdist-reference.text | 131 ++++++++++++ .../to_check/cdist-environment-variables.text | 191 ------------------ 3 files changed, 132 insertions(+), 191 deletions(-) create mode 100644 doc/man/cdist-reference.text delete mode 100644 doc/man/to_check/cdist-environment-variables.text diff --git a/Makefile b/Makefile index 6a880c48..689b4a5a 100644 --- a/Makefile +++ b/Makefile @@ -22,6 +22,7 @@ MANSRC=$(MANDIR)/cdist.text \ $(MANDIR)/cdist-bin-transfer.text \ $(MANDIR)/cdist-deploy-to.text \ $(MANDIR)/cdist-manifest.text \ + $(MANDIR)/cdist-reference.text \ $(MANDIR)/cdist-stages.text \ $(MANDIR)/cdist-type.text \ $(MANDIR)/cdist-type-template.text \ diff --git a/doc/man/cdist-reference.text b/doc/man/cdist-reference.text new file mode 100644 index 00000000..72ee4f48 --- /dev/null +++ b/doc/man/cdist-reference.text @@ -0,0 +1,131 @@ +cdist-reference(7) +================== +Nico Schottelius + +NAME +---- +cdist-reference - Variable, path and type reference + + +DESCRIPTION +----------- +Various scripts which are not in the core need information on how +to find information. This manpage summarises the available environment +variables and paths and clearifies with part may access with variables. + + +PATHS +----- +If not specified otherwise, all paths are relative to the checkout directory. + +conf/:: + Contains the (static) configuration like manifests, types and explorers. + +conf/manifest/init:: + This is the central entry point used by cdist-manifest-init(1). + It is an executable (+x bit set) shell script that can use + values from the explorers to decide which configuration to create + for the specified target host. + + It should be primary used to define mapping from configurations to hosts. + +conf/manifest/*:: + All other files in this directory are not directly used by Cdist, but you + can seperate configuration mappings, if you have a lot of code in the + manifest/init file. This may also be very helpful to have different admins + maintain different groups of hosts. + +conf/explorer/: + Contains explorers to be run on the target hosts, see cdist-explorer(7). + +conf/type/: + Contains all available types, which are used to provide + some kind of functionality. See cdist-type(7). + +conf/type//:: + Home of the type . + + This directory is referenced by the variable __type (see below). + +conf/type//manifest:: + Used to generate additional objects from a type. + +conf/type//gencode:: + Used to generate code to be executed on the client. + +conf/type//parameters/required:: + Parameters required by type, \n seperated list. + +conf/type//parameters/optional:: + Parameters optionally accepted by type, \n seperated list. + +conf/type//explorer:: + Location of the type specific explorers. + + This directory is referenced by the variable __type_explorer (see below). + + See cdist-explorer(7). + +out/: + This directory contains output of cdist and is usually located + in a temporary directory and thus will be removed after the run. + + This directory is referenced by the variable __global (see below). + +out/explorer:: + Output of general explorers. + +out/object:: + Objects created for the host. + +out/object/:: + Contains all object specific information. + + This directory is referenced by the variable __object (see below). + +out/object//explorers:: + Output of type specific explorers, per object. + +tmp_dir: Temporary storage: + A tempdir and a tempfile is used by cdist internally, + which will be removed when the scripts end automatically. + See cdist-config(1). + + +VARIABLES +--------- +__explorer:: + Directory that contains all explorers + Available for: explorer +__manifest:: + Directory that contains the initial manifest + Available for: initial manifest +__global:: + Directory that contains generic output like explorer + Available for: initial manifest, type manifest, type explorer, type codegen +__object:: + Directory that contains the current object + Available for: type manifest, type explorer, type codegen +__object_id:: + The type unique object id + Available for: type manifest, type explorer, type codegen +__target_host:: + The host we are deploying to. + Available for: initial manifest, type manifest, type codegen +__type:: + Path to the current type + Available for: type manifest +__type_explorers:: + Directory that contains the type explorers + Available for: type explorer + + +SEE ALSO +-------- +- cdist(7) + + +COPYING +------- +Copyright \(C) 2011 Nico Schottelius. Free use of this software is +granted under the terms of the GNU General Public License version 3 (GPLv3). diff --git a/doc/man/to_check/cdist-environment-variables.text b/doc/man/to_check/cdist-environment-variables.text deleted file mode 100644 index f39366f0..00000000 --- a/doc/man/to_check/cdist-environment-variables.text +++ /dev/null @@ -1,191 +0,0 @@ -cdist-reference(7) -================== -Nico Schottelius - -NAME ----- -cdist-reference - Variables, paths and types offered by cdist - - -DESCRIPTION ------------ -Various scripts which are not in the core need information on how -to find information. This manpage summarises the available environment -variables and clearifies with part may access with variables. - -PATHS ------ - - --------------------------------------------------------------------------------- -cdist-config-layout(7) -====================== -Nico Schottelius - - -NAME ----- -cdist-config-layout - Usage of paths in cdist - - -DESCRIPTION ------------ -If not specified otherwise, all paths are relative to the configuration -directory, which is normally /etc/cdist (but can be changed using environment -variables, see cdist-environment(7)). - -- conf_dir/: - Contains the (static) configuration like manifests, types and - explorers. - -- conf_dir/manifest/init: - This is the central entry point used by cdist-manifest-init(1). - It is an executable (+x bit set) shell script that can use - values from the explorers to decide which configuration to create - for the specified target host. - - It should be primary used to define mapping from configurations to hosts. - -- conf_dir/manifest/*: - All other files in this directory are not directly used by Cdist, but you - can seperate configuration mappings, if you have a lot of code in the - manifest/init file. This may also be very helpful to have different admins - maintain different groups of hosts. - -- conf_dir/explorer/ - Contains explorers to be run on the target hosts, see cdist-explorers(7). - -- conf_dir/type/ - Contains all available types, which are used to provide - some kind of functionality. See cdist-stages(7). - -- conf_dir/type//manifest: - Used to generate additional objects from a type. - See cdist-stages(7), cdist-types(7). - -- conf_dir/type//gencode: - Used to generate code to be executed on the client. - See cdist-types(7). - -- conf_dir/type//parameters/required: - Parameters required by type, \n seperated list. - See cdist-types(7). - -- conf_dir/type//parameters/optional: - Parameters optionally accepted by type, \n seperated list. - See cdist-types(7). - -- conf_dir/type//explorer: - Location of the type specific explorers. - See cdist-explorers(7). - -- out_dir/ - This directory contains output of cdist and is mirrored into the - cache after a successful run. This directory may be placed below - the tmpdir or at any other location and is also available on the - target. - -- out_dir/explorer: - Output of general explorers. - -- out_dir/object: - Objects created for the host. - -- out_dir/object//explorers: - Output of type specific explorers, per object. - -- tmp_dir: Temporary storage - A tempdir and a tempfile is provided by cdist-config(1), which - will be removed when the scripts ends automatically. - - -FUTURE ------- -The following functionality may be implemented in one of the next releases: - -- cache_dir/ - The cache contains the out_dir from previous runs, which - may also be used in types to gather information about other hosts - (like ssh-keys). - -- cache_dir/host/: - Contains the last out_dir of the specific host. - - -AUTHOR ------- -Nico Schottelius - - -RESOURCES ---------- -Main web site: http://www.nico.schottelius.org/cdist/[] - - -COPYING -------- -Copyright \(C) 2010-2011 Nico Schottelius. Free use of this software is -granted under the terms of the GNU General Public License version 3 (GPLv3). --------------------------------------------------------------------------------- - - - -VARIABLES ---------- -__explorer:: - Directory that contains all explorers -__manifest:: - Directory that contains the initial manifest -__global:: - Directory that contains generic output like explorer -__object:: - Directory that contains the current object -__object_id:: - The type unique object id -__type_explorers:: - Directory that contains the type explorers - - -EXPLORER --------- -- __explorer - - -INITIAL MANIFEST ----------------- -- __manifest -- __global - - -TYPE MANIFEST -------------- -- __object -- __object_id -- __global - - -TYPE EXPLORER -------------- -- __object -- __object_id -- __type_explorers -- __global - - -TYPE CODEGEN ------------- -- __object -- __object_id -- __global - - - -SEE ALSO --------- -- cdist(7) - - -COPYING -------- -Copyright \(C) 2011 Nico Schottelius. Free use of this software is -granted under the terms of the GNU General Public License version 3 (GPLv3). From 2277880e4b75868300f7c958e50a289ae917c831 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Wed, 9 Mar 2011 09:52:43 +0100 Subject: [PATCH 06/11] in theory finish type-listing to reference migration Signed-off-by: Nico Schottelius --- Makefile | 6 +- ...reference.text => cdist-reference.text.sh} | 74 ++++++++++++++-- doc/man/cdist-type-listing.text.sh | 87 ------------------- 3 files changed, 70 insertions(+), 97 deletions(-) rename doc/man/{cdist-reference.text => cdist-reference.text.sh} (67%) mode change 100644 => 100755 delete mode 100755 doc/man/cdist-type-listing.text.sh diff --git a/Makefile b/Makefile index 689b4a5a..9e3460f7 100644 --- a/Makefile +++ b/Makefile @@ -16,7 +16,7 @@ MANSRC=$(MANDIR)/cdist-config-layout.text \ $(MANDIR)/cdist-stages.text \ $(MANDIR)/cdist-terms.text \ -MANGENERATED=$(MANDIR)/cdist-type-listing.text +MANGENERATED=$(MANDIR)/cdist-reference.text MANSRC=$(MANDIR)/cdist.text \ $(MANDIR)/cdist-bin-transfer.text \ @@ -52,8 +52,8 @@ doc/man/.marker: $(MANSRC) $(MANGENERATED) touch $@ # Only depends on cdist-type__*.text in reality -$(MANDIR)/cdist-type-listing.text: $(MANSRC) $(MANDIR)/cdist-type-listing.text.sh - $(MANDIR)/cdist-type-listing.text.sh +$(MANDIR)/cdist-reference.text: $(MANSRC) $(MANDIR)/cdist-reference.text.sh + $(MANDIR)/cdist-reference.text.sh clean: diff --git a/doc/man/cdist-reference.text b/doc/man/cdist-reference.text.sh old mode 100644 new mode 100755 similarity index 67% rename from doc/man/cdist-reference.text rename to doc/man/cdist-reference.text.sh index 72ee4f48..c8a49abd --- a/doc/man/cdist-reference.text +++ b/doc/man/cdist-reference.text.sh @@ -1,17 +1,53 @@ +#!/bin/sh +# +# 2010-2011 Nico Schottelius (nico-cdist at schottelius.org) +# +# This file is part of cdist. +# +# cdist is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# cdist is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with cdist. If not, see . +# +# +# Generate manpage that lists available types +# + +__cdist_pwd="$(pwd -P)" +__cdist_mydir="${0%/*}"; +__cdist_abs_mydir="$(cd "$__cdist_mydir" && pwd -P)" +__cdist_myname=${0##*/}; +__cdist_abs_myname="$__cdist_abs_mydir/$__cdist_myname" + +filename="${__cdist_myname%.sh}" +dest="$__cdist_abs_mydir/$filename" + +cd "$__cdist_abs_mydir" + +# exec > "$dest" +cat << eof cdist-reference(7) ================== Nico Schottelius NAME ---- -cdist-reference - Variable, path and type reference +cdist-reference - Variable, path and type reference for cdist $(git describe) DESCRIPTION ----------- Various scripts which are not in the core need information on how to find information. This manpage summarises the available environment -variables and paths and clearifies with part may access with variables. +variables, types and paths and clearifies with part may access which variables. PATHS @@ -30,15 +66,15 @@ conf/manifest/init:: It should be primary used to define mapping from configurations to hosts. conf/manifest/*:: - All other files in this directory are not directly used by Cdist, but you + All other files in this directory are not directly used by cdist, but you can seperate configuration mappings, if you have a lot of code in the manifest/init file. This may also be very helpful to have different admins maintain different groups of hosts. -conf/explorer/: +conf/explorer/:: Contains explorers to be run on the target hosts, see cdist-explorer(7). -conf/type/: +conf/type/:: Contains all available types, which are used to provide some kind of functionality. See cdist-type(7). @@ -66,7 +102,7 @@ conf/type//explorer:: See cdist-explorer(7). -out/: +out/:: This directory contains output of cdist and is usually located in a temporary directory and thus will be removed after the run. @@ -86,11 +122,26 @@ out/object/:: out/object//explorers:: Output of type specific explorers, per object. -tmp_dir: Temporary storage: +tmp_dir:: A tempdir and a tempfile is used by cdist internally, which will be removed when the scripts end automatically. See cdist-config(1). +TYPES +----- +The following types are available: + +eof +for type in cdist-type__*.text; do + name_1="${type#cdist-type}" + name_2="${name_1%.text}" + + name="$name_2" + echo "- $name" +done + +cat << eof + VARIABLES --------- @@ -123,9 +174,18 @@ __type_explorers:: SEE ALSO -------- - cdist(7) +eof +for type in cdist-type__*.text; do + name_2="${type%.text}" + name="$name_2" + echo "- ${name}(7)" +done + +cat <. -# -# -# Generate manpage that lists available types -# - -__cdist_pwd="$(pwd -P)" -__cdist_mydir="${0%/*}"; -__cdist_abs_mydir="$(cd "$__cdist_mydir" && pwd -P)" -__cdist_myname=${0##*/}; -__cdist_abs_myname="$__cdist_abs_mydir/$__cdist_myname" - -filename="${__cdist_myname%.sh}" -dest="$__cdist_abs_mydir/$filename" - -cd "$__cdist_abs_mydir" - -exec > "$dest" - -cat << eof -cdist-type-listing(7) -===================== -Nico Schottelius - - -NAME ----- -cdist-type-listing - Available types in cdist - - -SYNOPSIS --------- -Types that are included in cdist $(git describe). - - -DESCRIPTION ------------ -The following types are available: - -eof -for type in cdist-type__*.text; do - name_1="${type#cdist-type}" - name_2="${name_1%.text}" - - name="$name_2" - echo "- $name" -done - -cat << eof - - -SEE ALSO --------- -- cdist-type(7) -eof -for type in cdist-type__*.text; do - name_2="${type%.text}" - - name="$name_2" - echo "- ${name}(7)" -done - -cat < Date: Wed, 9 Mar 2011 10:01:14 +0100 Subject: [PATCH 07/11] update pointers to cdist-reference Signed-off-by: Nico Schottelius --- Makefile | 1 - doc/changelog | 2 +- doc/man/.gitignore | 2 +- doc/man/cdist-deploy-to.text | 8 ++++---- doc/man/cdist-reference.text.sh | 16 ++++++++-------- doc/man/cdist-stages.text | 13 +++++++------ 6 files changed, 21 insertions(+), 21 deletions(-) diff --git a/Makefile b/Makefile index 9e3460f7..96924c4c 100644 --- a/Makefile +++ b/Makefile @@ -22,7 +22,6 @@ MANSRC=$(MANDIR)/cdist.text \ $(MANDIR)/cdist-bin-transfer.text \ $(MANDIR)/cdist-deploy-to.text \ $(MANDIR)/cdist-manifest.text \ - $(MANDIR)/cdist-reference.text \ $(MANDIR)/cdist-stages.text \ $(MANDIR)/cdist-type.text \ $(MANDIR)/cdist-type-template.text \ diff --git a/doc/changelog b/doc/changelog index 528b7e86..b39c512d 100644 --- a/doc/changelog +++ b/doc/changelog @@ -1,5 +1,5 @@ 1.0.2: upcoming - * Add manpages: cdist-type, cdist-type__file + * Add manpages: cdist-type, cdist-type__file, cdist-reference * Make doc/man/ usable as MANPATH entry 1.0.1: 2011-03-08 diff --git a/doc/man/.gitignore b/doc/man/.gitignore index 299485e8..8ed9d1e1 100644 --- a/doc/man/.gitignore +++ b/doc/man/.gitignore @@ -1,4 +1,4 @@ cdist.7 *.html cdist-design.7 -cdist-type-listing.text +cdist-reference.text diff --git a/doc/man/cdist-deploy-to.text b/doc/man/cdist-deploy-to.text index e09cba0a..acbb915a 100644 --- a/doc/man/cdist-deploy-to.text +++ b/doc/man/cdist-deploy-to.text @@ -30,10 +30,10 @@ variables are handled by cdist-config. SEE ALSO -------- -cdist(7), -cdist-config(1), -cdist-config-layout(7), -cdist-stages(7) +- cdist(7) +- cdist-config(1) +- cdist-reference(7) +- cdist-stages(7) COPYING diff --git a/doc/man/cdist-reference.text.sh b/doc/man/cdist-reference.text.sh index c8a49abd..2453c216 100755 --- a/doc/man/cdist-reference.text.sh +++ b/doc/man/cdist-reference.text.sh @@ -32,7 +32,7 @@ dest="$__cdist_abs_mydir/$filename" cd "$__cdist_abs_mydir" -# exec > "$dest" +exec > "$dest" cat << eof cdist-reference(7) ================== @@ -146,28 +146,28 @@ cat << eof VARIABLES --------- __explorer:: - Directory that contains all explorers + Directory that contains all explorers. Available for: explorer __manifest:: - Directory that contains the initial manifest + Directory that contains the initial manifest. Available for: initial manifest __global:: - Directory that contains generic output like explorer + Directory that contains generic output like explorer. Available for: initial manifest, type manifest, type explorer, type codegen __object:: - Directory that contains the current object + Directory that contains the current object. Available for: type manifest, type explorer, type codegen __object_id:: - The type unique object id + The type unique object id. Available for: type manifest, type explorer, type codegen __target_host:: The host we are deploying to. Available for: initial manifest, type manifest, type codegen __type:: - Path to the current type + Path to the current type. Available for: type manifest __type_explorers:: - Directory that contains the type explorers + Directory that contains the type explorers. Available for: type explorer diff --git a/doc/man/cdist-stages.text b/doc/man/cdist-stages.text index da6f4e02..4ab93cff 100644 --- a/doc/man/cdist-stages.text +++ b/doc/man/cdist-stages.text @@ -46,10 +46,9 @@ no conflicts may occur, i.e. no object of the same type with the same id may be created. Related manpages: + - cdist-manifest(7) - cdist-manifest-run(1) - cdist-manifest-run-init(1) - - cdist-manifest(7) - - cdist-config-layout(7) STAGE 3: EXECUTION OF TYPES @@ -67,9 +66,9 @@ may occur during the merge. A conflict would mean that two different objects try to create the same object, which indicates a broken configuration. Related manpages: - - cdist-type(7) - cdist-manifest-run(1) - cdist-manifest-run-all(1) + - cdist-type(7) STAGE 4: CODE GENERATION @@ -81,9 +80,9 @@ on stdout. If the gencode executable fails, it must print diagnostic messages on stderr and exit non-zero. Related manpages: - - cdist-types-gencode(7) - cdist-gencode(1) - cdist-gencode-all(1) + - cdist-type(7) STAGE 5: CODE EXECUTION @@ -92,8 +91,8 @@ The resulting code from the previous stage is transferred to the target host and executed there to apply the configuration changes, Related manpages: - - cdist-exec-transfer(1) - cdist-exec-run(1) + - cdist-exec-transfer(1) SUMMARY @@ -106,7 +105,9 @@ in correct order. SEE ALSO -------- -cdist(7), cdist-deploy-to(1), cdist-config-layout(7) +- cdist(7) +- cdist-deploy-to(1) +- cdist-reference(7) COPYING From a8c5f225b2b6427704fabffefb467e812312fb35 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Wed, 9 Mar 2011 10:03:06 +0100 Subject: [PATCH 08/11] --todo Signed-off-by: Nico Schottelius --- Makefile | 2 ++ doc/dev/todo/niconext | 5 +---- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/Makefile b/Makefile index 96924c4c..ca86ac4d 100644 --- a/Makefile +++ b/Makefile @@ -9,6 +9,7 @@ WEBDIR=$$HOME/niconetz WEBPAGE=software/cdist.mdwn MANDIR=doc/man +# Unchecked MANSRC=$(MANDIR)/cdist-config-layout.text \ $(MANDIR)/cdist-config.text \ $(MANDIR)/cdist-explorer.text \ @@ -16,6 +17,7 @@ MANSRC=$(MANDIR)/cdist-config-layout.text \ $(MANDIR)/cdist-stages.text \ $(MANDIR)/cdist-terms.text \ +# Clean documentation MANGENERATED=$(MANDIR)/cdist-reference.text MANSRC=$(MANDIR)/cdist.text \ diff --git a/doc/dev/todo/niconext b/doc/dev/todo/niconext index f7acbe88..55598bfd 100644 --- a/doc/dev/todo/niconext +++ b/doc/dev/todo/niconext @@ -1,5 +1,2 @@ Documentation cleanup - - document environment variables - - and merge with config-layout! - - how to debug explorer - => 1.0.2 + - how to debug explorer => 1.0.2 From 19d3b52d73b05b735994221eae8582b2047800e7 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Wed, 9 Mar 2011 10:16:46 +0100 Subject: [PATCH 09/11] finish manpage cdist-explorer Signed-off-by: Nico Schottelius --- Makefile | 2 +- doc/changelog | 2 +- doc/man/cdist-explorer.text | 66 ++++++++++++++++++++++++++++ doc/man/to_check/cdist-explorer.text | 43 ------------------ 4 files changed, 68 insertions(+), 45 deletions(-) create mode 100644 doc/man/cdist-explorer.text delete mode 100644 doc/man/to_check/cdist-explorer.text diff --git a/Makefile b/Makefile index ca86ac4d..adf03e31 100644 --- a/Makefile +++ b/Makefile @@ -12,7 +12,6 @@ MANDIR=doc/man # Unchecked MANSRC=$(MANDIR)/cdist-config-layout.text \ $(MANDIR)/cdist-config.text \ - $(MANDIR)/cdist-explorer.text \ $(MANDIR)/cdist-quickstart.text \ $(MANDIR)/cdist-stages.text \ $(MANDIR)/cdist-terms.text \ @@ -23,6 +22,7 @@ MANGENERATED=$(MANDIR)/cdist-reference.text MANSRC=$(MANDIR)/cdist.text \ $(MANDIR)/cdist-bin-transfer.text \ $(MANDIR)/cdist-deploy-to.text \ + $(MANDIR)/cdist-explorer.text \ $(MANDIR)/cdist-manifest.text \ $(MANDIR)/cdist-stages.text \ $(MANDIR)/cdist-type.text \ diff --git a/doc/changelog b/doc/changelog index b39c512d..4c356111 100644 --- a/doc/changelog +++ b/doc/changelog @@ -1,5 +1,5 @@ 1.0.2: upcoming - * Add manpages: cdist-type, cdist-type__file, cdist-reference + * Add manpages: cdist-type, cdist-type__file, cdist-reference, cdist-explorer * Make doc/man/ usable as MANPATH entry 1.0.1: 2011-03-08 diff --git a/doc/man/cdist-explorer.text b/doc/man/cdist-explorer.text new file mode 100644 index 00000000..9e40ca4b --- /dev/null +++ b/doc/man/cdist-explorer.text @@ -0,0 +1,66 @@ +cdist-explorer(7) +================= +Nico Schottelius + + +NAME +---- +cdist-explorer - Explore the target systems + + +DESCRIPTION +----------- +Explorer are small shell scripts, which will be executed on the target +host. The aim of the explorer is to give hints to types on how to act on the +target system. An explorer outputs the result to stdout, which is usually +a one liner, but may be empty or multi line especially in the case of +type explorers. + +There are general explorers, which are run in an early stage, and +type explorers. Both work almost exactly the same way, with the difference +that the values of the general explorers are stored in a general location and +the type specific below the object. + +Explorers can reuse other explorers on the target system by calling +$__explorer/ (general and type explorer) or +$__type_explorer/ (type explorer). + +In case of significant errors, the explorer may exit non-zero and return an +error message on stderr, which will cause the cdist run to abort. + + +EXAMPLES +-------- +A very simple explorer may look like this: + +-------------------------------------------------------------------------------- +hostname +-------------------------------------------------------------------------------- + +Which is in practise the "hostname" explorer. + +A type explorer, which could check for the status of a package may look like this: + +-------------------------------------------------------------------------------- +if [ -f "$__object/parameter/name" ]; then + name="$(cat "$__object/parameter/name")" +else + name="$__object_id" +fi + +# Except dpkg failing, if package is not known / installed +dpkg -s "$name" 2>/dev/null || exit 0 +-------------------------------------------------------------------------------- + + +SEE ALSO +-------- +- cdist(7) +- cdist-reference(7) +- cdist-stages(7) + + +COPYING +------- +Copyright \(C) 2010-2011 Nico Schottelius. Free use of this software is +granted under the terms of the GNU General Public License version 3 (GPLv3). diff --git a/doc/man/to_check/cdist-explorer.text b/doc/man/to_check/cdist-explorer.text deleted file mode 100644 index 659a01e1..00000000 --- a/doc/man/to_check/cdist-explorer.text +++ /dev/null @@ -1,43 +0,0 @@ -cdist-explorer(7) -================= -Nico Schottelius - - -NAME ----- -cdist-explorer - Explore the target systems - - -DESCRIPTION ------------ -Cdist explorer are small shell scripts, which will be executed -on the target host. The aim of the explorer is to give hints -to types on how to act on the target system. -The explorer output the result of its investigation -to stdout and should be a one-liner. The output may be empty, -though. - -Cdist knows about general explorers, which are run in an early -stage and type specific explorers. Both work exactly the same way, -with the difference that the values of the general explorers -are stored in a general location and the type specific below -the types. - -Explorers can reuse other explorers on the target system -by calling ./ (i.e. explorers are run -from their location). - -In case of significant errors, the shell script may exit -non-zero and return an error message on stderr, which -will cause the cdist run to abort. - - -SEE ALSO --------- -cdist(7), cdist-config-layout(7), cdist-stages(7) - - -COPYING -------- -Copyright \(C) 2010-2011 Nico Schottelius. Free use of this software is -granted under the terms of the GNU General Public License version 3 (GPLv3). From adb9ed9ca506400da3f5c0adecc08e2499771efe Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Wed, 9 Mar 2011 10:17:43 +0100 Subject: [PATCH 10/11] hint on debug / explorer Signed-off-by: Nico Schottelius --- doc/dev/todo/niconext | 1 - doc/man/cdist-explorer.text | 2 ++ 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/dev/todo/niconext b/doc/dev/todo/niconext index 55598bfd..04dfc21b 100644 --- a/doc/dev/todo/niconext +++ b/doc/dev/todo/niconext @@ -1,2 +1 @@ Documentation cleanup - - how to debug explorer => 1.0.2 diff --git a/doc/man/cdist-explorer.text b/doc/man/cdist-explorer.text index 9e40ca4b..63c7a5c9 100644 --- a/doc/man/cdist-explorer.text +++ b/doc/man/cdist-explorer.text @@ -28,6 +28,8 @@ $__type_explorer/ (type explorer). In case of significant errors, the explorer may exit non-zero and return an error message on stderr, which will cause the cdist run to abort. +You can also use stderr for debugging purposes while developing a new +explorer. EXAMPLES -------- From 579d58625bcc3694ae61d5fbabafa7dbca3ebdf4 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Wed, 9 Mar 2011 10:36:58 +0100 Subject: [PATCH 11/11] setup date in changelog Signed-off-by: Nico Schottelius --- doc/changelog | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/changelog b/doc/changelog index 4c356111..4ec2c47f 100644 --- a/doc/changelog +++ b/doc/changelog @@ -1,4 +1,4 @@ -1.0.2: upcoming +1.0.2: 2011-03-09 * Add manpages: cdist-type, cdist-type__file, cdist-reference, cdist-explorer * Make doc/man/ usable as MANPATH entry