forked from ungleich-public/cdist
bc436c6c5c
Signed-off-by: Nico Schottelius <nico@kr.ethz.ch>
152 lines
5 KiB
Text
152 lines
5 KiB
Text
cdist-type(7)
|
|
==============
|
|
Nico Schottelius <nico-cdist--@--schottelius.org>
|
|
|
|
|
|
NAME
|
|
----
|
|
cdist-type - Functionality bundled
|
|
|
|
|
|
SYNOPSIS
|
|
--------
|
|
Other languages name this module or class
|
|
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
Types are the main component of cdist and define functionality. If you
|
|
use cdist, you'll write a type for every functionality you would like
|
|
to use.
|
|
|
|
|
|
|
|
Was man mit cdist type machen kann.....
|
|
|
|
A cdist type describes some kind of functionality, starting from simple stuff
|
|
like copying files until complex user auth/ldap/ kerberos infrastructure
|
|
designs. The name of every type is prefixed with two underscores (__) 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
|
|
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)
|
|
- gencode (optional)
|
|
- explorer (optional)
|
|
|
|
Types are stored below conf/type/. Their name should always be prefixed with
|
|
two underscores (__) to prevent collisions with other binaries in $PATH.
|
|
|
|
To begin a new type from a template, execute "cdist-type-template __NAME"
|
|
and cd 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.
|
|
|
|
WRITING THE GENCODE SCRIPT
|
|
--------------------------
|
|
|
|
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 there is a corresponding manpage named cdist-type-NAME (without
|
|
underscores) included.
|
|
|
|
|
|
SEE ALSO
|
|
--------
|
|
- cdist-manifest-run(1)
|
|
|
|
|
|
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).
|