diff --git a/.gitignore b/.gitignore index 099d7de3..ba65e3f8 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ .*.swp doc/man/*.[1-9] doc/man/.marker +doc/man/man*/ diff --git a/Makefile b/Makefile index 23b7962d..ddada4c3 100644 --- a/Makefile +++ b/Makefile @@ -17,9 +17,12 @@ MANSRC=$(MANDIR)/cdist-config-layout.text \ $(MANDIR)/cdist-terms.text \ $(MANDIR)/cdist-type.text -MANSRC=$(MANDIR)/cdist.text \ - $(MANDIR)/cdist-deploy-to.text \ - $(MANDIR)/cdist-manifest.text \ +MANSRC=$(MANDIR)/cdist.text \ + $(MANDIR)/cdist-bin-transfer.text \ + $(MANDIR)/cdist-deploy-to.text \ + $(MANDIR)/cdist-manifest.text \ + $(MANDIR)/cdist-stages.text \ + $(MANDIR)/cdist-type-template.text \ ################################################################################ @@ -41,7 +44,7 @@ man: doc/man/.marker doc/man/.marker: $(MANSRC) for mansrc in $(MANSRC); do $(A2X) $$mansrc; done - for manpage in $(MANDIR)/*.[1-9]; do cat=$${manpage##*.}; echo $$cat; mandir=$(MANDIR)/man$$cat; mkdir -p $$mandir; mv $$manpage $$mandir; done + for manpage in $(MANDIR)/*.[1-9]; do cat=$${manpage##*.}; mandir=$(MANDIR)/man$$cat; mkdir -p $$mandir; mv $$manpage $$mandir; done touch $@ clean: diff --git a/REAL_README b/REAL_README index 7cefb29e..10b1b812 100644 --- a/REAL_README +++ b/REAL_README @@ -53,14 +53,6 @@ but is not. Or: The reason why I began to write cdist. * sh * find, rm, ... -### Roadmap - -[[!table data=""" -**Version** | **Objectives** | **Status** -1.0.0 | Initial release | -1.0.1 | Documentation cleanup | -"""]] - ## Requirements ### Server diff --git a/bin/cdist-config b/bin/cdist-config index fd0ae9ab..7f68ca67 100755 --- a/bin/cdist-config +++ b/bin/cdist-config @@ -196,13 +196,14 @@ __cdist_type_gencode() echo "${__cdist_type_dir}/$1/${__cdist_name_gencode}" } -__cdist_type_param_file() +__cdist_type_parameter_dir() { - # FIXME: local == posix? - local type="$1"; shift - local paramtype="$1"; shift + echo "$(__cdist_type_dir "$1")/${__cdist_name_parameter}" +} - echo "${__cdist_type_dir}/${type}/${__cdist_name_parameter}/${paramtype}" +__cdist_type_parameter_file() +{ + echo "$(__cdist_type_parameter_dir "$1")/$2" } __cdist_type_from_object() diff --git a/bin/cdist-deploy-to b/bin/cdist-deploy-to index c576dfd6..5d06cf96 100755 --- a/bin/cdist-deploy-to +++ b/bin/cdist-deploy-to @@ -58,7 +58,7 @@ cdist-manifest-run-all "$__cdist_target_host" "$__cdist_out_object_dir" cdist-object-explorer-all "$__cdist_target_host" "$__cdist_out_object_dir" # Generate code for all objects -cdist-object-codegen-all "$__cdist_target_host" "$__cdist_out_object_dir" +cdist-object-gencode-all "$__cdist_target_host" "$__cdist_out_object_dir" # Transfer all objects including code cdist-dir push "$__cdist_target_host" "$__cdist_out_object_dir" \ diff --git a/bin/cdist-object-codegen b/bin/cdist-object-gencode similarity index 100% rename from bin/cdist-object-codegen rename to bin/cdist-object-gencode diff --git a/bin/cdist-object-codegen-all b/bin/cdist-object-gencode-all similarity index 96% rename from bin/cdist-object-codegen-all rename to bin/cdist-object-gencode-all index 67f05186..40c39fd4 100755 --- a/bin/cdist-object-codegen-all +++ b/bin/cdist-object-gencode-all @@ -39,7 +39,7 @@ while read object; do code="$(__cdist_object_code "$object")" echo "Generating code for $object ..." - cdist-object-codegen "$__cdist_target_host" \ + cdist-object-gencode "$__cdist_target_host" \ "$__cdist_object_base_dir" \ "$object" > "${code}" diff --git a/bin/cdist-type-emulator b/bin/cdist-type-emulator index 9283052d..69be9405 100755 --- a/bin/cdist-type-emulator +++ b/bin/cdist-type-emulator @@ -78,14 +78,14 @@ while read required; do fi mv "${tempparameter}/${required}" "${__cdist_parameter_dir}" -done < "$(__cdist_type_param_file "$__cdist_type" "$__cdist_name_parameter_required")" +done < "$(__cdist_type_parameter_file "$__cdist_type" "$__cdist_name_parameter_required")" # Allow optional parameters while read optional; do if [ -f "${tempparameter}/${optional}" ]; then mv "${tempparameter}/${optional}" "${__cdist_parameter_dir}" fi -done < "$(__cdist_type_param_file "$__cdist_type" "$__cdist_name_parameter_optional")" +done < "$(__cdist_type_parameter_file "$__cdist_type" "$__cdist_name_parameter_optional")" # Error out on other paramaters cd "${tempparameter}" diff --git a/bin/cdist-type-template b/bin/cdist-type-template new file mode 100755 index 00000000..0391510c --- /dev/null +++ b/bin/cdist-type-template @@ -0,0 +1,66 @@ +#!/bin/sh +# +# 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 . +# +# +# Create a new type from scratch +# + +. cdist-config +[ $# -eq 1 ] || __cdist_usage "" +set -eu + +__cdist_type="$1"; shift + + +# Base +mkdir -p "$(__cdist_type_dir "$__cdist_type")" + +# Parameter +mkdir -p "$(__cdist_type_parameter_dir "$__cdist_type")" +touch "$(__cdist_type_parameter_dir "$__cdist_type")/${__cdist_name_parameter_required}" +touch "$(__cdist_type_parameter_dir "$__cdist_type")/${__cdist_name_parameter_optional}" + +# Manifest +cat "$__cdist_abs_mydir/../doc/dev/header" - << eof > "$(__cdist_type_parameter_dir "$__cdist_type")/${__cdist_name_manifest}" + +# +# This is the manifest, which can be used to create other objects like this: +# __file /path/to/destination --source /from/where/ --type file +# +# To tell cdist to make use of it, you need to make it executable (chmod +x) +# +# + +eof + +# Gencode +cat "$__cdist_abs_mydir/../doc/dev/header" - << eof > "$(__cdist_type_parameter_dir "$__cdist_type")/${__cdist_name_gencode}" + +# +# This file should generate code on stdout, which will be collected by cdist +# and run on the target. +# +# To tell cdist to make use of it, you need to make it executable (chmod +x) +# +# + +eof + +# Explorer +mkdir -p "$(__cdist_type_parameter_dir "$__cdist_type")/${__cdist_name_explorer}" diff --git a/doc/changelog b/doc/changelog new file mode 100644 index 00000000..179afd8d --- /dev/null +++ b/doc/changelog @@ -0,0 +1,7 @@ +1.0.1: 2011-03-08 + * Added cdist-type-template including manpage + * Fix manpage building + * Add new manpages: cdist-stages, cdist-bin-transfer + +1.0.0: 2011-03-07 + * Initial release diff --git a/doc/dev/header b/doc/dev/header index 6e673ae2..5c3ce870 100755 --- a/doc/dev/header +++ b/doc/dev/header @@ -1,6 +1,6 @@ #!/bin/sh # -# 2010-2011 Nico Schottelius (nico-cdist at schottelius.org) +# 2011 Nico Schottelius (nico-cdist at schottelius.org) # # This file is part of cdist. # @@ -18,3 +18,5 @@ # along with cdist. If not, see . # # +# USEFUL DESCRIPTION +# diff --git a/doc/dev/todo/niconext b/doc/dev/todo/niconext index 6a7da465..4f8f033d 100644 --- a/doc/dev/todo/niconext +++ b/doc/dev/todo/niconext @@ -1 +1,8 @@ -Prepare release 1.0.0 +Documentation cleanup + - to_check/cdist-type.text + - cdist-type-integration + - Ensure available types are documented (!) + - define how to in cdist-type-integration + - referenced on the webpage via cdist-type(7)! + + - how to debug explorer and codegen diff --git a/doc/dev/todo/post-1.0 b/doc/dev/todo/post-1.0 index e469214e..de8919f0 100644 --- a/doc/dev/todo/post-1.0 +++ b/doc/dev/todo/post-1.0 @@ -1,9 +1,6 @@ Core: - Support singletons (see types/issue for a good reason) - probably name them only_once and use that as the internal id! - - remove remote_base_dir at beginning - otherwise fragments from - previous runs may still be existing! - -> probably also local_base_dir! - cdist-deploy-to: Configure more than one host - plus parallel mode like in ccollect @@ -51,13 +48,11 @@ Documentation: + cdist + cdist-deploy-to + cdist-manifest - - cdist-quickstart: how to get started - cdist-type [IMPORTANT] - only do necessary work [TYPE IMPLEMENTATION HINTS] - install packages only if not existent - copy file only if different - DOC document that $type/manifest is executed for every object/instance - - cdist-explorer - exported variables: - general explorer: __explorer # cdist-explorer - initial manifest: __manifest, __global # cdist-manifest @@ -65,12 +60,11 @@ Documentation: - type explorers: __object, __object_id, __type_explorers # cdist-type - type codegen: __object, __object_id, __global # cdist-type - type code: - # cdist-code - - cdist-type-integration - - Ensure available types are documented (!) - - define how to in cdist-type-integration - - referenced on the webpage via cdist-type(7)! + - category 7: + - cdist-manifest(7) + - cdist-explorer + - cdist-config-layout - ensure every file in bin/ has a correspondent manpage - - cdist-bin-transfer - cdist-code-run-all - cdist-config - cdist-deploy-to diff --git a/doc/man/cdist-bin-transfer.text b/doc/man/cdist-bin-transfer.text new file mode 100644 index 00000000..21f00b65 --- /dev/null +++ b/doc/man/cdist-bin-transfer.text @@ -0,0 +1,30 @@ +cdist-bin-transfer(1) +===================== +Nico Schottelius + + +NAME +---- +cdist-bin-transfer - Transfer binaries to the target + + +SYNOPSIS +-------- +cdist-deploy-to HOSTNAME REMOTE_DIR + + +DESCRIPTION +----------- +cdist-bin-transfer copies all cdist binaries to the given host HOSTNAME +into the given directory REMOTE_DIR. These binaries will be used in +further stages to retrieve information or apply configurations. + +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-stages.text b/doc/man/cdist-stages.text similarity index 70% rename from doc/man/to_check/cdist-stages.text rename to doc/man/cdist-stages.text index f82f9046..da6f4e02 100644 --- a/doc/man/to_check/cdist-stages.text +++ b/doc/man/cdist-stages.text @@ -16,14 +16,25 @@ Reading the source of the cdist-deploy-to executable shous the scripts responsible for each stage. +STAGE 0: INTERNAL PREPERATION +----------------------------- +Before running the user facing stages, cdist prepares the target host +to contain cdist binaries and creates a clean environment for the +configuration run. + +Related manpages: + - cdist-bin-transfer(1) + + STAGE 1: TARGET INFORMATION RETRIEVAL -------------------------------------- -In this stage information is collected about target using so called explorers. -Every existing explorer is run on the target and the output of all explorers -are copied back into the local cache. The results can be used by manifests and -types. +In this stage information is collected about the target host using so called +explorers. Every existing explorer is run on the target and the output of all +explorers are copied back into the local cache. The results can be used by +manifests and types. -Related manpages are cdist-explorers(7) and cdist-cache(7). +Related manpages: + - cdist-explorer(7) STAGE 2: RUN THE INITIAL MANIFEST @@ -34,8 +45,11 @@ the objects as defined in the manifest for the specific host. In this stage, no conflicts may occur, i.e. no object of the same type with the same id may be created. -Related manpages are cdist-manifest-init(1), cdist-manifests(7) and -cdist-config-layout(7). +Related manpages: + - cdist-manifest-run(1) + - cdist-manifest-run-init(1) + - cdist-manifest(7) + - cdist-config-layout(7) STAGE 3: EXECUTION OF TYPES @@ -46,13 +60,16 @@ may generate and change the created objects. In other words, one type can reuse other types. For instance the object __apache/www.test.ch is of type __apache, which may -contain an manifest script, which creates new objects of type __file. +contain a manifest script, which creates new objects of type __file. The newly created objects are merged back into the existing tree. No conflicts 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 manpage are cdist-types(7) and cdist-manifest-run-all(1). +Related manpages: + - cdist-type(7) + - cdist-manifest-run(1) + - cdist-manifest-run-all(1) STAGE 4: CODE GENERATION @@ -63,8 +80,10 @@ be executed. This executable should create code to be executed on the target on stdout. If the gencode executable fails, it must print diagnostic messages on stderr and exit non-zero. -Related manpages are cdist-types-gencode(7), cdist-gencode(1) and -cdist-gencode-all(1). +Related manpages: + - cdist-types-gencode(7) + - cdist-gencode(1) + - cdist-gencode-all(1) STAGE 5: CODE EXECUTION @@ -72,7 +91,9 @@ STAGE 5: CODE EXECUTION The resulting code from the previous stage is transferred to the target host and executed there to apply the configuration changes, -Related manpages are cdist-exec-transfer(1) and cdist-exec-run(1). +Related manpages: + - cdist-exec-transfer(1) + - cdist-exec-run(1) SUMMARY @@ -85,7 +106,7 @@ in correct order. SEE ALSO -------- -cdist(7), cdist-deploy-to(1), cdist-config-layout(7), cdist-manifest-init(1) +cdist(7), cdist-deploy-to(1), cdist-config-layout(7) COPYING diff --git a/doc/man/cdist-type-template.text b/doc/man/cdist-type-template.text new file mode 100644 index 00000000..bbd31409 --- /dev/null +++ b/doc/man/cdist-type-template.text @@ -0,0 +1,30 @@ +cdist-type-template(1) +====================== +Nico Schottelius + + +NAME +---- +cdist-type-template - Create a new type + + +SYNOPSIS +-------- +cdist-type-template NAME + + +DESCRIPTION +----------- +cdist-type-template creates a new type and adds the usual files to it. +It is thought to be helpful when writing new types. + + +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-type.text b/doc/man/to_check/cdist-type.text index a2e2cc49..9e9642a1 100644 --- a/doc/man/to_check/cdist-type.text +++ b/doc/man/to_check/cdist-type.text @@ -1,18 +1,34 @@ -cdist-types(7) -=============== +cdist-type(7) +============== Nico Schottelius NAME ---- -cdist-types - Functionality bundled +cdist-type - Functionality bundled + + +SYNOPSIS +-------- +Other languages name this module or class 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. + + + +Was man mit cdist type machen kann..... + A cdist type describes some kind of functionality, starting from simple stuff like copying files until complex user auth/ldap/ kerberos infrastructure -designs. The name of every type is prefixed with two underscores (__), because +designs. The name of every type is prefixed with two underscores (__) by convention. + + +, because types will be executed and the two underscores prevent collisions with real binaries (like "file"). In general, types should be written independent of hosts (as in reusable @@ -37,11 +53,33 @@ Every time a type is used, a new object is created of the specific type, with a type specific unique id that stores the parameters +HOW TO WRITE A NEW TYPE +----------------------- +A type consists of + +- parameter (required) +- manifest (optional) +- gencode (optional) +- explorer (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 to conf/type/__NAME. + + +DEFINING PARAMETERS +------------------- +Every type consists of optional and + + HOW TO WRITE A NEW TYPE (TODO) ------------------------------ -Assume you want to create the new type named "coffee": +Assume you want to create the new type named "coffee", which creates +files which contain the word "c0ffee". -Create the directory /etc/cdist/types/coffee/ +Create the directory conf/type/coffee/. Create the file /etc/cdist/types/coffee/README containing a description of the type. If your type supports attributes, create the directory /etc/cdist/types/coffee/