diff --git a/Makefile b/Makefile index e003c0c6..adf03e31 100644 --- a/Makefile +++ b/Makefile @@ -9,21 +9,25 @@ 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 \ $(MANDIR)/cdist-quickstart.text \ $(MANDIR)/cdist-stages.text \ $(MANDIR)/cdist-terms.text \ +# Clean documentation +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 \ $(MANDIR)/cdist-type-template.text \ - $(MANDIR)/cdist-type__file.text \ + $(MANDIR)/cdist-type__file.text \ ################################################################################ @@ -43,13 +47,18 @@ 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-reference.text: $(MANSRC) $(MANDIR)/cdist-reference.text.sh + $(MANDIR)/cdist-reference.text.sh + + 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 diff --git a/doc/changelog b/doc/changelog index b0087c36..4ec2c47f 100644 --- a/doc/changelog +++ b/doc/changelog @@ -1,5 +1,5 @@ -1.0.2: upcoming - * Add manpages: cdist-type +1.0.2: 2011-03-09 + * 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/dev/todo/niconext b/doc/dev/todo/niconext index 636cd561..04dfc21b 100644 --- a/doc/dev/todo/niconext +++ b/doc/dev/todo/niconext @@ -1,4 +1 @@ Documentation cleanup - - document environment variables - - Reference all types somewhere (on the webpage?) - - how to debug explorer diff --git a/doc/man/.gitignore b/doc/man/.gitignore index 22d0a62d..8ed9d1e1 100644 --- a/doc/man/.gitignore +++ b/doc/man/.gitignore @@ -1,3 +1,4 @@ cdist.7 *.html cdist-design.7 +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-explorer.text b/doc/man/cdist-explorer.text new file mode 100644 index 00000000..63c7a5c9 --- /dev/null +++ b/doc/man/cdist-explorer.text @@ -0,0 +1,68 @@ +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. + +You can also use stderr for debugging purposes while developing a new +explorer. + +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/cdist-reference.text.sh b/doc/man/cdist-reference.text.sh new file mode 100755 index 00000000..2453c216 --- /dev/null +++ b/doc/man/cdist-reference.text.sh @@ -0,0 +1,191 @@ +#!/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 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, types and paths and clearifies with part may access which 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:: + 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 +--------- +__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) +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" - -exit 0 - -cat << eof > "$dest" -cdist-type-listing(7) -===================== -Nico Schottelius - - -NAME ----- -cdist-type-listing - Available types in cdist - - -SYNOPSIS --------- -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. - - -HOW TO USE A TYPE ------------------ -You can use types from the initial manifest or the type manifest like a -normal command: - --------------------------------------------------------------------------------- -# 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. - - -SEE ALSO --------- -- cdist-manifest-run(1) -- cdist-stages(7) - - -COPYING -------- -Copyright \(C) 2011-$(date +%Y) Nico Schottelius. Free use of this software is -granted under the terms of the GNU General Public License version 3 (GPLv3). - -eof 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 ----------------------- 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 deleted file mode 100644 index c91a2ae0..00000000 --- a/doc/man/to_check/cdist-environment-variables.text +++ /dev/null @@ -1,14 +0,0 @@ -Update on env: - - 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: - - - -- __object: Path to the object that we are working on -- __object_id: type unique object id -- __global: contains global information (see cdist-env - 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).