Merge remote branch 'nico/master'
This commit is contained in:
Steven Armstrong
commit
c7262f65ed
9 changed files with 347 additions and 60 deletions
5
Makefile
5
Makefile
|
|
@ -15,14 +15,15 @@ MANSRC=$(MANDIR)/cdist-config-layout.text \
|
|||
$(MANDIR)/cdist-quickstart.text \
|
||||
$(MANDIR)/cdist-stages.text \
|
||||
$(MANDIR)/cdist-terms.text \
|
||||
$(MANDIR)/cdist-type.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.text \
|
||||
$(MANDIR)/cdist-type-template.text \
|
||||
$(MANDIR)/cdist-type__file.text \
|
||||
|
||||
|
||||
################################################################################
|
||||
|
|
@ -48,7 +49,7 @@ doc/man/.marker: $(MANSRC)
|
|||
touch $@
|
||||
|
||||
clean:
|
||||
rm -f doc/man/*.html doc/man/*.[1-9]
|
||||
rm -rf doc/man/*.html doc/man/*.[1-9] doc/man/man[1-9]
|
||||
|
||||
################################################################################
|
||||
# Developer targets
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,7 @@
|
|||
1.0.2: upcoming
|
||||
* Add manpages: cdist-type
|
||||
* Make doc/man/ usable as MANPATH entry
|
||||
|
||||
1.0.1: 2011-03-08
|
||||
* Added cdist-type-template including manpage
|
||||
* Fix manpage building
|
||||
|
|
|
|||
|
|
@ -1,8 +1,4 @@
|
|||
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
|
||||
- document environment variables
|
||||
- Reference all types somewhere (on the webpage?)
|
||||
- how to debug explorer
|
||||
|
|
|
|||
|
|
@ -38,12 +38,6 @@ Documentation:
|
|||
- via version control
|
||||
- Define how to raise errors in types
|
||||
|
||||
- = todo
|
||||
+ = in progress -> S|N
|
||||
x = done
|
||||
|
||||
|
||||
x remove old documentation from doc/man/!
|
||||
- Check all references in manpages, ensure all manpages exist, generic ones:
|
||||
+ cdist
|
||||
+ cdist-deploy-to
|
||||
|
|
@ -53,13 +47,6 @@ Documentation:
|
|||
- install packages only if not existent
|
||||
- copy file only if different
|
||||
- DOC document that $type/manifest is executed for every object/instance
|
||||
- exported variables:
|
||||
- general explorer: __explorer # cdist-explorer
|
||||
- initial manifest: __manifest, __global # cdist-manifest
|
||||
- type manifests __object, __object_id, __global # cdist-type
|
||||
- type explorers: __object, __object_id, __type_explorers # cdist-type
|
||||
- type codegen: __object, __object_id, __global # cdist-type
|
||||
- type code: - # cdist-code
|
||||
- category 7:
|
||||
- cdist-manifest(7)
|
||||
- cdist-explorer
|
||||
|
|
|
|||
203
doc/man/cdist-type-listing.text.sh
Normal file
203
doc/man/cdist-type-listing.text.sh
Normal file
|
|
@ -0,0 +1,203 @@
|
|||
#!/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
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
cdist-type(7)
|
||||
==============
|
||||
=============
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
|
|
@ -20,39 +20,6 @@ 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 (__) 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
|
||||
code), but may be used implement functionality only needed on one host
|
||||
as well.
|
||||
It must be assumed that the clients are pretty dumb and thus do 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 must create an object of the specific type.
|
||||
If the generated code fails on the client, it must print diagnostistic messages on
|
||||
stderr and exit non-zero, so the configuration is aborted.
|
||||
Types may make use of other types to realise a new type or may implement some
|
||||
functionality on their own.
|
||||
|
||||
Types may consist of
|
||||
- a number of required and optional parameters they accept,
|
||||
- a manifest script that makes use of the parameters and may create other objects
|
||||
- explorers that explore type specific information on the target
|
||||
- a gencode script, that may generate code to be executed on the target
|
||||
|
||||
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 USE A TYPE
|
||||
-----------------
|
||||
You can use types from the initial manifest or the type manifest like a
|
||||
|
|
@ -77,8 +44,8 @@ A type consists of
|
|||
|
||||
- parameter (optional)
|
||||
- manifest (optional)
|
||||
- gencode (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.
|
||||
|
|
@ -128,8 +95,55 @@ 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
|
||||
-----------------------------------------
|
||||
|
|
@ -137,16 +151,16 @@ 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 there is a corresponding manpage named cdist-type-NAME (without
|
||||
underscores) included.
|
||||
Ensure a corresponding manpage named cdist-type__NAME is included.
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- cdist-manifest-run(1)
|
||||
- cdist-stages(7)
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
Copyright \(C) 2010-2011 Nico Schottelius. Free use of this software is
|
||||
Copyright \(C) 2011 Nico Schottelius. Free use of this software is
|
||||
granted under the terms of the GNU General Public License version 3 (GPLv3).
|
||||
59
doc/man/cdist-type__file.text
Normal file
59
doc/man/cdist-type__file.text
Normal file
|
|
@ -0,0 +1,59 @@
|
|||
cdist-type__file(7)
|
||||
===================
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
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).
|
||||
14
doc/man/to_check/cdist-environment-variables.text
Normal file
14
doc/man/to_check/cdist-environment-variables.text
Normal file
|
|
@ -0,0 +1,14 @@
|
|||
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
|
||||
|
||||
Loading…
Reference in a new issue