From c7811fb056a5d77fbab18b3afd2bcf939d2adfa0 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Fri, 12 Jul 2013 19:36:49 +0200 Subject: [PATCH] restore cdist-type.text Signed-off-by: Nico Schottelius --- docs/man/man7/cdist-type.text | 280 ++++++++++++++++++++++++++++++++++ 1 file changed, 280 insertions(+) create mode 100644 docs/man/man7/cdist-type.text diff --git a/docs/man/man7/cdist-type.text b/docs/man/man7/cdist-type.text new file mode 100644 index 00000000..cfb50414 --- /dev/null +++ b/docs/man/man7/cdist-type.text @@ -0,0 +1,280 @@ +cdist-type(7) +============= +Nico Schottelius + + +NAME +---- +cdist-type - Functionality bundled + + +SYNOPSIS +-------- +__TYPE ID --parameter value [--parameter value ...] + +__TYPE --parameter value [--parameter value ...] (for singletons) + + +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 +-------------------------------------------------------------------------------- + +A list of supported types can be found in the cdist-reference(7) manpage. + + +SINGLETON TYPES +--------------- +If a type is flagged as a singleton, it may be used only +once per host. This is useful for types which can be used only once on a +system. Singleton types do not take an object name as argument. + +Example: +-------------------------------------------------------------------------------- +# __issue type manages /etc/issue +__issue + +# Probably your own type - singletons may use parameters +__myfancysingleton --colour green +-------------------------------------------------------------------------------- + + +HOW TO WRITE A NEW TYPE +----------------------- +A type consists of + +- parameter (optional) +- manifest (optional) +- singleton (optional) +- explorer (optional) +- gencode (optional) + +Types are stored below cdist/conf/type/. Their name should always be prefixed with +two underscores (__) to prevent collisions with other executables in $PATH. + +To implement a new type, create the directory **cdist/conf/type/__NAME**. + + +DEFINING PARAMETERS +------------------- +Every type consists of required, optional and boolean parameters, which must +each be declared in a newline separated file in ***parameter/required***, +***parameter/required_multiple***, ***parameter/optional***, +***parameter/optional_multiple*** and ***parameter/boolean***. +Parameters which are allowed multiple times should be listed in +required_multiple or optional_multiple respectively. All other parameters +follow the standard unix behaviour "the last given wins". +If either is missing, the type will have no required, no optional, no boolean +or no parameters at all. + +Example: +-------------------------------------------------------------------------------- +echo servername >> cdist/conf/type/__nginx_vhost/parameter/required +echo logdirectory >> cdist/conf/type/__nginx_vhost/parameter/optional +echo server_alias >> cdist/conf/type/__nginx_vhost/parameter/optional_multiple +echo use_ssl >> cdist/conf/type/__nginx_vhost/parameter/boolean +-------------------------------------------------------------------------------- + + +USING PARAMETERS +---------------- +The parameters given to a type can be accessed and used in all type scripts +(e.g manifest, gencode-*, explorer/*). Note that boolean parameters are +represented by file existence. File exists -> True, +file does not exist -> False + +Example: (e.g. in cdist/conf/type/__nginx_vhost/manifest) +-------------------------------------------------------------------------------- +# required parameter +servername="$(cat "$__object/parameter/servername")" + +# optional parameter +if [ -f "$__object/parameter/logdirectory" ]; then + logdirectory="$(cat "$__object/parameter/logdirectory")" +fi + +# boolean parameter +if [ -f "$__object/parameter/use_ssl" ]; then + # file exists -> True + # do some fancy ssl stuff +fi + +# parameter with multiple values +if [ -f "$__object/parameter/server_alias" ]; then + for alias in $(cat "$__object/parameter/server_alias"); do + echo $alias > /some/where/usefull + done +fi + +-------------------------------------------------------------------------------- + + +INPUT FROM STDIN +---------------- +Every type can access what has been written on stdin when it has been called. +The result is saved into the ***stdin*** file in the object directory. + +Example use of a type: (e.g. in cdist/conf/type/__archlinux_hostname) +-------------------------------------------------------------------------------- +__file /etc/rc.conf --source - << eof +... +HOSTNAME="$__target_host" +... +eof +-------------------------------------------------------------------------------- +If you have not seen this syntax (<< eof) before, it may help you to read +about "here documents". + +In the __file type, stdin is used as source for the file, if - is used for source: + +-------------------------------------------------------------------------------- + if [ -f "$__object/parameter/source" ]; then + source="$(cat "$__object/parameter/source")" + if [ "$source" = "-" ]; then + source="$__object/stdin" + fi + .... +-------------------------------------------------------------------------------- + + +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-reference(7). + +Always ensure the manifest is executable, otherwise cdist will not be able +to execute it. For more information about manifests see cdist-manifest(7). + + +SINGLETON - ONE INSTANCE ONLY +----------------------------- +If you want to ensure that a type can only be used once per target, you can +mark it as a singleton: Just create the (empty) file "singleton" in your type +directory: + +-------------------------------------------------------------------------------- +touch cdist/conf/type/__NAME/singleton +-------------------------------------------------------------------------------- + +This will also change the way your type must be called: + +-------------------------------------------------------------------------------- +__YOURTYPE --parameter value +-------------------------------------------------------------------------------- + +As you can see, the object ID is omitted, because it does not make any sense, +if your type can be used only once. + + +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 the 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 +-------------------------- +There are two gencode scripts: ***gencode-local*** and ***gencode-remote***. +The output of gencode-local is executed locally, whereas +the output of gencode-remote is executed on the target. +The gencode scripts can make use of the parameters, the global explorers +and the type specific explorers. + +If the gencode scripts 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. + +If your type wants to save temporary data, that may be used by other types +later on (for instance __file), you can save them in the subdirectory +"files" below $__object (but you must create it yourself). +cdist will not touch this directory. + +If your type contains static files, it's also recommended to place them in +a folder named "files" within the type (again, because cdist guarantees to +never ever touch this folder). + + +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 have a look at cdist-hacker(7) on +how to submit it. + +SEE ALSO +-------- +- cdist-explorer(7) +- cdist-hacker(7) +- cdist-stages(7) +- cdist-tutorial(7) + + +COPYING +------- +Copyright \(C) 2011-2012 Nico Schottelius. Free use of this software is +granted under the terms of the GNU General Public License version 3 (GPLv3).