diff --git a/Makefile b/Makefile index deefbafd..a6d78aeb 100644 --- a/Makefile +++ b/Makefile @@ -9,16 +9,20 @@ 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 \ @@ -42,13 +46,35 @@ all: 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##*.}; mandir=$(MANDIR)/man$$cat; mkdir -p $$mandir; mv $$manpage $$mandir; done +doc/man/.marker: $(MANDIR)/cdist-reference.text touch $@ +# Manual from core +mancore: $(MANSRC) + for mansrc in $^; do $(A2X) $$mansrc; done + +# Manuals from types +mantype: + for man in conf/type/*/man.text; do $(A2X) $$man; done + +# Move into manpath directories +manmove: mantype mancore + for manpage in $(MANDIR)/*.[1-9] conf/type/*/*.7; do \ + cat=$${manpage##*.}; \ + mandir=$(MANDIR)/man$$cat; \ + mkdir -p $$mandir; \ + mv $$manpage $$mandir; \ + done + +# Reference depends on conf/type/*/man.text - HOWTO with posix make? +$(MANDIR)/cdist-reference.text: manmove $(MANDIR)/cdist-reference.text.sh + $(MANDIR)/cdist-reference.text.sh + $(A2X) $(MANDIR)/cdist-reference.text + # Move us to the destination as well + make manmove + 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/REAL_README b/REAL_README index 10b1b812..ab070b38 100644 --- a/REAL_README +++ b/REAL_README @@ -79,6 +79,10 @@ To install cdist, execute the following commands: cd cdist export PATH=$PATH:$(pwd -P)/bin + # If you want the manpages + make man + export MANPATH=$MANPATH:$(pwd -P)/doc/man + Afterwards you can run ***cdist-quickstart*** to get an impression on how to use cdist. @@ -105,6 +109,11 @@ To upgrade cdist in the current branch use git pull + # Also update the manpages + make man + export MANPATH=$MANPATH:$(pwd -P)/doc/man + + The version branches are designed to change if there are incompatibilities. Or the other way round: As long as you stay on 1.0 and do git pull, nothing should break. diff --git a/bin/cdist-config b/bin/cdist-config index 7f68ca67..54984eaf 100755 --- a/bin/cdist-config +++ b/bin/cdist-config @@ -57,13 +57,14 @@ __cdist_abs_myname="$__cdist_abs_mydir/$__cdist_myname" : ${__cdist_name_parameter:=parameter} : ${__cdist_name_parameter_required:=required} : ${__cdist_name_parameter_optional:=optional} +: ${__cdist_name_singleton:=singleton} : ${__cdist_name_target_host:=target_host} : ${__cdist_name_type:=type} : ${__cdist_name_type_bin:=type_bin} : ${__cdist_name_type_explorer:=type_explorer} -# Used for IDs -: ${__cdist_sane_regexp:=[A-Za-z0-9/]*[-A-Za-z0-9_/]*} +# Used for IDs: Allow everything not starting with - and . +: ${__cdist_sane_regexp:=[^-\.].*} # Default remote user : ${__cdist_remote_user:=root} @@ -162,11 +163,6 @@ __cdist_init_deploy() ln -sf "$__cdist_conf_dir" "$__cdist_local_base_dir/$__cdist_name_conf_dir" } -# __cdist_cache_host() -# { -# echo "${__cdist_cache_hosts}/${__cdist_target_host}" -# } - __cdist_type_has_explorer() { # We only create output, if there's at least one explorer @@ -196,14 +192,25 @@ __cdist_type_gencode() echo "${__cdist_type_dir}/$1/${__cdist_name_gencode}" } +__cdist_type_singleton() +{ + echo "${__cdist_type_dir}/$1/${__cdist_name_singleton}" +} + __cdist_type_parameter_dir() { echo "$(__cdist_type_dir "$1")/${__cdist_name_parameter}" } -__cdist_type_parameter_file() +# Shorthand for required and optional +__cdist_type_parameter_required() { - echo "$(__cdist_type_parameter_dir "$1")/$2" + echo "$(__cdist_type_parameter_dir "$1")/$__cdist_name_parameter_required" +} + +__cdist_type_parameter_optional() +{ + echo "$(__cdist_type_parameter_dir "$1")/$__cdist_name_parameter_optional" } __cdist_type_from_object() diff --git a/bin/cdist-type-emulator b/bin/cdist-type-emulator index 69be9405..a4f66e5b 100755 --- a/bin/cdist-type-emulator +++ b/bin/cdist-type-emulator @@ -25,12 +25,18 @@ # . cdist-config -[ $# -ge 1 ] || __cdist_usage " " set -eu -__cdist_object_id="$1"; shift __cdist_type="$__cdist_myname" +# Find out whether type is a singleton or regular type +if [ -f "$(__cdist_type_singleton "$__cdist_type")" ]; then + __cdist_object_id="singleton" +else + [ $# -ge 1 ] || __cdist_usage " " + __cdist_object_id="$1"; shift +fi + echo "$__cdist_object_id" | grep -q "^${__cdist_sane_regexp}\$" || \ __cdist_usage "Insane object id, ${__cdist_object_id}." @@ -72,20 +78,24 @@ while [ $# -gt 0 ]; do done # Ensure required parameters are given -while read required; do - if [ ! -f "${tempparameter}/${required}" ]; then - __cdist_usage "Missing required parameter $required" - fi +if [ -f "$(__cdist_type_parameter_required "$__cdist_type")" ]; then + while read required; do + if [ ! -f "${tempparameter}/${required}" ]; then + __cdist_usage "Missing required parameter $required" + fi - mv "${tempparameter}/${required}" "${__cdist_parameter_dir}" -done < "$(__cdist_type_parameter_file "$__cdist_type" "$__cdist_name_parameter_required")" + mv "${tempparameter}/${required}" "${__cdist_parameter_dir}" + done < "$(__cdist_type_parameter_required "$__cdist_type")" +fi # Allow optional parameters -while read optional; do - if [ -f "${tempparameter}/${optional}" ]; then - mv "${tempparameter}/${optional}" "${__cdist_parameter_dir}" - fi -done < "$(__cdist_type_parameter_file "$__cdist_type" "$__cdist_name_parameter_optional")" +if [ -f "$(__cdist_type_parameter_optional "$__cdist_type")" ]; then + while read optional; do + if [ -f "${tempparameter}/${optional}" ]; then + mv "${tempparameter}/${optional}" "${__cdist_parameter_dir}" + fi + done < "$(__cdist_type_parameter_optional "$__cdist_type")" +fi # Error out on other paramaters cd "${tempparameter}" diff --git a/conf/manifest/init b/conf/manifest/init index e6cf47d5..8a2428ce 100755 --- a/conf/manifest/init +++ b/conf/manifest/init @@ -3,32 +3,50 @@ # # This is debug and should not be in a production environment -echo "We could access other manifests in $__manifest" +# echo "We could access other manifests in $__manifest" +# Every machine becomes a marker, so sysadmins know that automatic +# configurations are happening __file /etc/cdist-configured --type file case "$__target_host" in # Everybody has this localhost) + # Usual example __file test --type file --destination /tmp/cdist-testfile ;; + # + # Examples using different types + # + # Alias in /etc/hosts for localhost cdist-archlinux) - __package_pacman django --state deinstalled - __package_pacman wireshark-cli --state installed + # This is the specific package type for pacman __package_pacman zsh --state installed + + # The __package type autoselect the right type based on the os + __package vim --state installed + + # If the type is a singleton, it does not take an object id + __issue ;; + # This is how it would look like on gentoo cdist-gentoo) + # Same stuff for gentoo __package tree --state installed ;; + cdist-debian) + __package_apt atop --state installed + __package apache2 --state deinstalled + ;; - # Real machines - ikq*) - __package_apt zsh --state installed - __package_apt apache2 --state deinstalled - ;; - kr) - __issue iddoesnotmatterhere - ;; + # Real machines may be used with their hostname or fqdn, + # depending on how you call cdist-deploy-to + # machine) + # ... + # ;; + # machine.example.org) + # ... + # ;; esac diff --git a/conf/type/__file/explorer/exists b/conf/type/__file/explorer/exists new file mode 100755 index 00000000..b0be82fc --- /dev/null +++ b/conf/type/__file/explorer/exists @@ -0,0 +1,34 @@ +#!/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 . +# +# +# Check whether file exists or not +# + +if [ -f "$__object/parameter/destination" ]; then + destination="$(cat "$__object/parameter/destination")" +else + destination="/$__object_id" +fi + +if [ -e "$destination" ]; then + echo yes +else + echo no +fi diff --git a/conf/type/__file/explorer/md5sum b/conf/type/__file/explorer/md5sum index b2867385..4ac0e1b9 100755 --- a/conf/type/__file/explorer/md5sum +++ b/conf/type/__file/explorer/md5sum @@ -41,7 +41,11 @@ esac # No output if file does not exist - does definitely not match the md5sum :-) if [ -e "$destination" ]; then - $md5sum < "$destination" + if [ -f "$destination" ]; then + $md5sum < "$destination" + else + echo "NO REGULAR FILE" + fi else echo "NO FILE FOUND, NO CHECKSUM CALCULATED." fi diff --git a/conf/type/__file/gencode b/conf/type/__file/gencode index 0f3b1bf8..9ad956fe 100755 --- a/conf/type/__file/gencode +++ b/conf/type/__file/gencode @@ -55,33 +55,38 @@ esac if [ -f "$__object/parameter/source" ]; then source="$(cat "$__object/parameter/source")" - local_md5sum="$($md5sum < "$source")" - remote_md5sum="$(cat "$__object/explorer/md5sum")" + if [ -f "$source" ]; then + local_md5sum="$($md5sum < "$source")" + remote_md5sum="$(cat "$__object/explorer/md5sum")" - # Is md5sum the right approach? - if [ "$local_md5sum" != "$remote_md5sum" ]; then - # FIXME: This is ugly and hardcoded, replace after 1.0! - # Probably a better aproach is to have the user configured - # ~/.ssh/config to contain the right username - # Probably describe it in cdist-quickstart... - scp "$source" "root@${__target_host}:${destination}" + # Is md5sum the right approach? + if [ "$local_md5sum" != "$remote_md5sum" ]; then + # FIXME: This is ugly and hardcoded, replace after 1.0! + # Probably a better aproach is to have the user configured + # ~/.ssh/config to contain the right username + # Probably describe it in cdist-quickstart... + scp "$source" "root@${__target_host}:${destination}" + fi fi # No source? Create empty file/dir else - case "$type" in - directory) - echo mkdir \"$destination\" - ;; + # Only touch / create if it does not exist + if [ no = "$(cat "$__object/explorer/exists")" ]; then + case "$type" in + directory) + echo mkdir \"$destination\" + ;; - file) - echo touch \"$destination\" - ;; + file) + echo touch \"$destination\" + ;; - *) - echo "Unsupported type: \"$type\"" >&2 - exit 1 - ;; - esac + *) + echo "Unsupported type: \"$type\"" >&2 + exit 1 + ;; + esac + fi fi if [ -f "$__object/parameter/mode" ]; then diff --git a/conf/type/__file/man.text b/conf/type/__file/man.text new file mode 100644 index 00000000..04e0ffc3 --- /dev/null +++ b/conf/type/__file/man.text @@ -0,0 +1,59 @@ +cdist-type__file(7) +=================== +Nico Schottelius + + +NAME +---- +cdist-type__file - Create files + + +DESCRIPTION +----------- +This cdist type allows you to create files on the target. + + +REQUIRED PARAMETERS +------------------- +type:: + Specifies the type of file to be created. Either "directory" or "file" + + +OPTIONAL PARAMETERS +------------------- +destination:: + If supplied, use this as the destination on the target. Otherwise the + object_id is used. + +mode:: + Unix permissions, suitable for chmod. + +source:: + If supplied, copy this file from the host running cdist to the target. + If not supplied, an empty file or directory will be created. + + +EXAMPLES +-------- + +-------------------------------------------------------------------------------- +# Create /etc/cdist-configured as an empty file +__file /etc/cdist-configured --type file + +# Same but with a different object id +__file cdist-marker --type file --destination /etc/cdist-configured + +# Use __file from another type +__file /etc/issue --source "$__type/files/archlinux" --type file +-------------------------------------------------------------------------------- + + +SEE ALSO +-------- +- cdist-type(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/conf/type/__issue/manifest b/conf/type/__issue/manifest index a79544ee..aa6f7629 100755 --- a/conf/type/__issue/manifest +++ b/conf/type/__issue/manifest @@ -20,7 +20,7 @@ # destination=/etc/issue -os="$(cat "out/explorer/os")" +source="$(cat "out/explorer/os")" case "$os" in archlinux) diff --git a/conf/type/__issue/singleton b/conf/type/__issue/singleton new file mode 100644 index 00000000..e69de29b diff --git a/conf/type/__package_apt/gencode b/conf/type/__package_apt/gencode index b451eb9f..413562d5 100755 --- a/conf/type/__package_apt/gencode +++ b/conf/type/__package_apt/gencode @@ -29,7 +29,7 @@ fi state="$(cat "$__object/parameter/state")" -is_installed="$(grep "^Status: install ok installed" "$__object/explorer/pkg_status")" +is_installed="$(grep "^Status: install ok installed" "$__object/explorer/pkg_status" || true)" case "$state" in installed) diff --git a/doc/changelog b/doc/changelog index b0087c36..2f528b90 100644 --- a/doc/changelog +++ b/doc/changelog @@ -1,5 +1,10 @@ -1.0.2: upcoming - * Add manpages: cdist-type +1.0.3: upcoming + * Update regexp used for sane characters + * Allow types without parameters + * Allow type to be singleton (DOCUMENTATION MISSING) + +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/logs/2011-03-09 b/doc/dev/logs/2011-03-09 new file mode 100644 index 00000000..4666ccb3 --- /dev/null +++ b/doc/dev/logs/2011-03-09 @@ -0,0 +1,3 @@ +Steven & Nico: +- types are closed in themselves +- manpage will be stored in conf/type/NAME/man.text diff --git a/doc/dev/todo/niconext b/doc/dev/todo/niconext index 636cd561..87b61b47 100644 --- a/doc/dev/todo/niconext +++ b/doc/dev/todo/niconext @@ -1,4 +1,3 @@ -Documentation cleanup - - document environment variables - - Reference all types somewhere (on the webpage?) - - how to debug explorer +- Support singletons (see types/issue for a good reason) + - add documentation! + diff --git a/doc/dev/todo/post-1.0 b/doc/dev/todo/post-1.0 index 9d6031b4..8ea11dd4 100644 --- a/doc/dev/todo/post-1.0 +++ b/doc/dev/todo/post-1.0 @@ -1,9 +1,3 @@ -Core: - - Support singletons (see types/issue for a good reason) - - probably name them only_once and use that as the internal id! - - cdist-deploy-to: Configure more than one host - - plus parallel mode like in ccollect - Type handler: - add dependency parameters to core available for every type --requires @@ -36,8 +30,6 @@ Documentation: - cdist-trigger after first run from /var/lib/cdist/out/bin? - Different environments (production, integration, development) - via version control - - Define how to raise errors in types - - Check all references in manpages, ensure all manpages exist, generic ones: + cdist + cdist-deploy-to @@ -47,10 +39,6 @@ Documentation: - install packages only if not existent - copy file only if different - DOC document that $type/manifest is executed for every object/instance - - category 7: - - cdist-manifest(7) - - cdist-explorer - - cdist-config-layout - ensure every file in bin/ has a correspondent manpage - cdist-code-run-all - cdist-config @@ -69,8 +57,10 @@ Documentation: - cdist-run-remote - cdist-type-build-emulation - cdist-type-emulator - - Cleanup READMEs - Ensure html output of manpages are published on the web +-------------------------------------------------------------------------------- +Fix: +Running initial manifest for sgv-wiki-01 ... +/tmp/cdist.VfhjaH8LP3GE/out/type_bin/__ethz_systems_wiki: Zeile 87: /home/users/nico/privat/firmen/ethz/vcs/cdist/conf/type/__ethz_systems_wiki/parameter/required: Datei oder Verzeichnis nicht gefunden +/tmp/cdist.VfhjaH8LP3GE/out/type_bin/__ethz_systems_wiki: Zeile 94: /home/users/nico/privat/firmen/ethz/vcs/cdist/conf/type/__ethz_systems_wiki/parameter/optional: Datei oder Verzeichnis nicht gefunden -- Makefile: - - Include manpage generation 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-manifest.text b/doc/man/cdist-manifest.text index 40ab2c4e..efa5a8eb 100644 --- a/doc/man/cdist-manifest.text +++ b/doc/man/cdist-manifest.text @@ -43,10 +43,10 @@ __file /etc/nologin --type file --source "$__type/files/default.nologin" SEE ALSO -------- -cdist-manifest-run(1), -cdist-manifest-run-all(1), -cdist-manifest-run-init(1), -cdist-type(7) +- cdist-manifest-run(1) +- cdist-manifest-run-all(1) +- cdist-manifest-run-init(1) +- cdist-type(7) COPYING diff --git a/doc/man/cdist-reference.text.sh b/doc/man/cdist-reference.text.sh new file mode 100755 index 00000000..f900e35e --- /dev/null +++ b/doc/man/cdist-reference.text.sh @@ -0,0 +1,195 @@ +#!/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//man.text:: + Manpage in Asciidoc format (nequired for inclusion into upstream) + +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 man7/cdist-type__*; do + name_1="${type#man7/cdist-type}" + name_2="${name_1%.7}" + + 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 man7/cdist-type__*; do + name_1="${type#man7/}" + name_2="${name_1%.7}" + + name="$name_2" + echo "- ${name}(7)" +done + +cat < - - -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).