cdist-type(7) ============== Nico Schottelius 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).