From a095b1a3c323b7a58db4bc999e2cffeb13785ded Mon Sep 17 00:00:00 2001 From: Nico Schottelius <nico@kr.ethz.ch> Date: Tue, 8 Mar 2011 21:47:08 +0100 Subject: [PATCH] finish manpage for cdist-type__file Signed-off-by: Nico Schottelius <nico@kr.ethz.ch> --- Makefile | 1 + doc/man/cdist-type__file.text | 173 +++++++--------------------------- 2 files changed, 34 insertions(+), 140 deletions(-) diff --git a/Makefile b/Makefile index deefbafd..e003c0c6 100644 --- a/Makefile +++ b/Makefile @@ -23,6 +23,7 @@ MANSRC=$(MANDIR)/cdist.text \ $(MANDIR)/cdist-stages.text \ $(MANDIR)/cdist-type.text \ $(MANDIR)/cdist-type-template.text \ + $(MANDIR)/cdist-type__file.text \ ################################################################################ diff --git a/doc/man/cdist-type__file.text b/doc/man/cdist-type__file.text index 3c7a1317..04e0ffc3 100644 --- a/doc/man/cdist-type__file.text +++ b/doc/man/cdist-type__file.text @@ -1,163 +1,56 @@ -cdist-type(7) -============= +cdist-type__file(7) +=================== Nico Schottelius <nico-cdist--@--schottelius.org> NAME ---- -cdist-type - Functionality bundled - - -SYNOPSIS --------- -Other languages name this module or class +cdist-type__file - Create files 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. +This cdist type allows you to create files on the target. -HOW TO USE A TYPE ------------------ -You can use types from the initial manifest or the type manifest like a -normal command: +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 +-------- -------------------------------------------------------------------------------- -# Creates empty file /etc/cdist-configured +# Create /etc/cdist-configured as an empty file __file /etc/cdist-configured --type file -# Ensure tree is installed -__package tree --state installed +# 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 -------------------------------------------------------------------------------- -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) +- cdist-type(7) COPYING