Merge remote branch 'nico/master'
This commit is contained in:
commit
f8d5da90fb
14 changed files with 294 additions and 394 deletions
19
Makefile
19
Makefile
|
@ -9,21 +9,25 @@ WEBDIR=$$HOME/niconetz
|
||||||
WEBPAGE=software/cdist.mdwn
|
WEBPAGE=software/cdist.mdwn
|
||||||
|
|
||||||
MANDIR=doc/man
|
MANDIR=doc/man
|
||||||
|
# Unchecked
|
||||||
MANSRC=$(MANDIR)/cdist-config-layout.text \
|
MANSRC=$(MANDIR)/cdist-config-layout.text \
|
||||||
$(MANDIR)/cdist-config.text \
|
$(MANDIR)/cdist-config.text \
|
||||||
$(MANDIR)/cdist-explorer.text \
|
|
||||||
$(MANDIR)/cdist-quickstart.text \
|
$(MANDIR)/cdist-quickstart.text \
|
||||||
$(MANDIR)/cdist-stages.text \
|
$(MANDIR)/cdist-stages.text \
|
||||||
$(MANDIR)/cdist-terms.text \
|
$(MANDIR)/cdist-terms.text \
|
||||||
|
|
||||||
|
# Clean documentation
|
||||||
|
MANGENERATED=$(MANDIR)/cdist-reference.text
|
||||||
|
|
||||||
MANSRC=$(MANDIR)/cdist.text \
|
MANSRC=$(MANDIR)/cdist.text \
|
||||||
$(MANDIR)/cdist-bin-transfer.text \
|
$(MANDIR)/cdist-bin-transfer.text \
|
||||||
$(MANDIR)/cdist-deploy-to.text \
|
$(MANDIR)/cdist-deploy-to.text \
|
||||||
|
$(MANDIR)/cdist-explorer.text \
|
||||||
$(MANDIR)/cdist-manifest.text \
|
$(MANDIR)/cdist-manifest.text \
|
||||||
$(MANDIR)/cdist-stages.text \
|
$(MANDIR)/cdist-stages.text \
|
||||||
$(MANDIR)/cdist-type.text \
|
$(MANDIR)/cdist-type.text \
|
||||||
$(MANDIR)/cdist-type-template.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
|
man: doc/man/.marker
|
||||||
|
|
||||||
doc/man/.marker: $(MANSRC)
|
doc/man/.marker: $(MANSRC) $(MANGENERATED)
|
||||||
for mansrc in $(MANSRC); do $(A2X) $$mansrc; done
|
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
|
for manpage in $(MANDIR)/*.[1-9]; do cat=$${manpage##*.}; mandir=$(MANDIR)/man$$cat; mkdir -p $$mandir; mv $$manpage $$mandir; done
|
||||||
touch $@
|
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:
|
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
|
# Developer targets
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
1.0.2: upcoming
|
1.0.2: 2011-03-09
|
||||||
* Add manpages: cdist-type
|
* Add manpages: cdist-type, cdist-type__file, cdist-reference, cdist-explorer
|
||||||
* Make doc/man/ usable as MANPATH entry
|
* Make doc/man/ usable as MANPATH entry
|
||||||
|
|
||||||
1.0.1: 2011-03-08
|
1.0.1: 2011-03-08
|
||||||
|
|
|
@ -1,4 +1 @@
|
||||||
Documentation cleanup
|
Documentation cleanup
|
||||||
- document environment variables
|
|
||||||
- Reference all types somewhere (on the webpage?)
|
|
||||||
- how to debug explorer
|
|
||||||
|
|
1
doc/man/.gitignore
vendored
1
doc/man/.gitignore
vendored
|
@ -1,3 +1,4 @@
|
||||||
cdist.7
|
cdist.7
|
||||||
*.html
|
*.html
|
||||||
cdist-design.7
|
cdist-design.7
|
||||||
|
cdist-reference.text
|
||||||
|
|
|
@ -30,10 +30,10 @@ variables are handled by cdist-config.
|
||||||
|
|
||||||
SEE ALSO
|
SEE ALSO
|
||||||
--------
|
--------
|
||||||
cdist(7),
|
- cdist(7)
|
||||||
cdist-config(1),
|
- cdist-config(1)
|
||||||
cdist-config-layout(7),
|
- cdist-reference(7)
|
||||||
cdist-stages(7)
|
- cdist-stages(7)
|
||||||
|
|
||||||
|
|
||||||
COPYING
|
COPYING
|
||||||
|
|
68
doc/man/cdist-explorer.text
Normal file
68
doc/man/cdist-explorer.text
Normal file
|
@ -0,0 +1,68 @@
|
||||||
|
cdist-explorer(7)
|
||||||
|
=================
|
||||||
|
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||||
|
|
||||||
|
|
||||||
|
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/<explorer_name> (general and type explorer) or
|
||||||
|
$__type_explorer/<explorer name> (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).
|
191
doc/man/cdist-reference.text.sh
Executable file
191
doc/man/cdist-reference.text.sh
Executable file
|
@ -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 <http://www.gnu.org/licenses/>.
|
||||||
|
#
|
||||||
|
#
|
||||||
|
# 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 <nico-cdist--@--schottelius.org>
|
||||||
|
|
||||||
|
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/<name>::
|
||||||
|
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/<name>/::
|
||||||
|
Home of the type <name>.
|
||||||
|
|
||||||
|
This directory is referenced by the variable __type (see below).
|
||||||
|
|
||||||
|
conf/type/<name>/manifest::
|
||||||
|
Used to generate additional objects from a type.
|
||||||
|
|
||||||
|
conf/type/<name>/gencode::
|
||||||
|
Used to generate code to be executed on the client.
|
||||||
|
|
||||||
|
conf/type/<name>/parameters/required::
|
||||||
|
Parameters required by type, \n seperated list.
|
||||||
|
|
||||||
|
conf/type/<name>/parameters/optional::
|
||||||
|
Parameters optionally accepted by type, \n seperated list.
|
||||||
|
|
||||||
|
conf/type/<name>/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/<object>::
|
||||||
|
Contains all object specific information.
|
||||||
|
|
||||||
|
This directory is referenced by the variable __object (see below).
|
||||||
|
|
||||||
|
out/object/<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 <<eof
|
||||||
|
|
||||||
|
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).
|
||||||
|
eof
|
|
@ -46,10 +46,9 @@ no conflicts may occur, i.e. no object of the same type with the same id may
|
||||||
be created.
|
be created.
|
||||||
|
|
||||||
Related manpages:
|
Related manpages:
|
||||||
|
- cdist-manifest(7)
|
||||||
- cdist-manifest-run(1)
|
- cdist-manifest-run(1)
|
||||||
- cdist-manifest-run-init(1)
|
- cdist-manifest-run-init(1)
|
||||||
- cdist-manifest(7)
|
|
||||||
- cdist-config-layout(7)
|
|
||||||
|
|
||||||
|
|
||||||
STAGE 3: EXECUTION OF TYPES
|
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.
|
try to create the same object, which indicates a broken configuration.
|
||||||
|
|
||||||
Related manpages:
|
Related manpages:
|
||||||
- cdist-type(7)
|
|
||||||
- cdist-manifest-run(1)
|
- cdist-manifest-run(1)
|
||||||
- cdist-manifest-run-all(1)
|
- cdist-manifest-run-all(1)
|
||||||
|
- cdist-type(7)
|
||||||
|
|
||||||
|
|
||||||
STAGE 4: CODE GENERATION
|
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.
|
on stderr and exit non-zero.
|
||||||
|
|
||||||
Related manpages:
|
Related manpages:
|
||||||
- cdist-types-gencode(7)
|
|
||||||
- cdist-gencode(1)
|
- cdist-gencode(1)
|
||||||
- cdist-gencode-all(1)
|
- cdist-gencode-all(1)
|
||||||
|
- cdist-type(7)
|
||||||
|
|
||||||
|
|
||||||
STAGE 5: CODE EXECUTION
|
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,
|
and executed there to apply the configuration changes,
|
||||||
|
|
||||||
Related manpages:
|
Related manpages:
|
||||||
- cdist-exec-transfer(1)
|
|
||||||
- cdist-exec-run(1)
|
- cdist-exec-run(1)
|
||||||
|
- cdist-exec-transfer(1)
|
||||||
|
|
||||||
|
|
||||||
SUMMARY
|
SUMMARY
|
||||||
|
@ -106,7 +105,9 @@ in correct order.
|
||||||
|
|
||||||
SEE ALSO
|
SEE ALSO
|
||||||
--------
|
--------
|
||||||
cdist(7), cdist-deploy-to(1), cdist-config-layout(7)
|
- cdist(7)
|
||||||
|
- cdist-deploy-to(1)
|
||||||
|
- cdist-reference(7)
|
||||||
|
|
||||||
|
|
||||||
COPYING
|
COPYING
|
||||||
|
|
|
@ -1,203 +0,0 @@
|
||||||
#!/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 <http://www.gnu.org/licenses/>.
|
|
||||||
#
|
|
||||||
#
|
|
||||||
# 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 <nico-cdist--@--schottelius.org>
|
|
||||||
|
|
||||||
|
|
||||||
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
|
|
|
@ -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
|
save the given parameters into a cconfig database, so they can be accessed by
|
||||||
the manifest and gencode scripts of the type (see below).
|
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
|
HOW TO WRITE A NEW TYPE
|
||||||
-----------------------
|
-----------------------
|
||||||
|
|
|
@ -29,12 +29,11 @@ pull mechanism (client requests configuration).
|
||||||
|
|
||||||
SEE ALSO
|
SEE ALSO
|
||||||
--------
|
--------
|
||||||
Website: http://www.nico.schottelius.org/cdist/[],
|
- Website: http://www.nico.schottelius.org/cdist/[]
|
||||||
cdist-deploy-to(1),
|
- cdist-deploy-to(1)
|
||||||
cdist-manifest(7),
|
- cdist-manifest(7)
|
||||||
cdist-quickstart(1),
|
- cdist-quickstart(1)
|
||||||
cdist-type(7),
|
- cdist-type(7)
|
||||||
cdist-type-inclusion(7)
|
|
||||||
|
|
||||||
|
|
||||||
COPYING
|
COPYING
|
||||||
|
|
|
@ -1,108 +0,0 @@
|
||||||
cdist-config-layout(7)
|
|
||||||
======================
|
|
||||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
|
||||||
|
|
||||||
|
|
||||||
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/<name>
|
|
||||||
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/<name>/manifest:
|
|
||||||
Used to generate additional objects from a type.
|
|
||||||
See cdist-stages(7), cdist-types(7).
|
|
||||||
|
|
||||||
- conf_dir/type/<name>/gencode:
|
|
||||||
Used to generate code to be executed on the client.
|
|
||||||
See cdist-types(7).
|
|
||||||
|
|
||||||
- conf_dir/type/<name>/parameters/required:
|
|
||||||
Parameters required by type, \n seperated list.
|
|
||||||
See cdist-types(7).
|
|
||||||
|
|
||||||
- conf_dir/type/<name>/parameters/optional:
|
|
||||||
Parameters optionally accepted by type, \n seperated list.
|
|
||||||
See cdist-types(7).
|
|
||||||
|
|
||||||
- conf_dir/type/<name>/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/<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/<name>:
|
|
||||||
Contains the last out_dir of the specific host.
|
|
||||||
|
|
||||||
|
|
||||||
AUTHOR
|
|
||||||
------
|
|
||||||
Nico Schottelius <mailto:nico-cdist--@--schottelius.org[]>
|
|
||||||
|
|
||||||
|
|
||||||
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).
|
|
|
@ -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
|
|
||||||
|
|
|
@ -1,43 +0,0 @@
|
||||||
cdist-explorer(7)
|
|
||||||
=================
|
|
||||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
|
||||||
|
|
||||||
|
|
||||||
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 ./<explorer_name> (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).
|
|
Loading…
Reference in a new issue