135 lines
14 KiB
HTML
135 lines
14 KiB
HTML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>cdist-type(7)</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /></head><body><div xml:lang="en" class="article" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="idm140257092560272"></a>cdist-type(7)</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Nico</span> <span class="surname">Schottelius</span></h3><code class="email"><<a class="email" href="mailto:nico-cdist--@--schottelius.org">nico-cdist--@--schottelius.org</a>></code></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="#_name">1. NAME</a></span></dt><dt><span class="section"><a href="#_synopsis">2. SYNOPSIS</a></span></dt><dt><span class="section"><a href="#_description">3. DESCRIPTION</a></span></dt><dt><span class="section"><a href="#_how_to_use_a_type">4. HOW TO USE A TYPE</a></span></dt><dt><span class="section"><a href="#_singleton_types">5. SINGLETON TYPES</a></span></dt><dt><span class="section"><a href="#_how_to_write_a_new_type">6. HOW TO WRITE A NEW TYPE</a></span></dt><dt><span class="section"><a href="#_defining_parameters">7. DEFINING PARAMETERS</a></span></dt><dt><span class="section"><a href="#_using_parameters">8. USING PARAMETERS</a></span></dt><dt><span class="section"><a href="#_input_from_stdin">9. INPUT FROM STDIN</a></span></dt><dt><span class="section"><a href="#_writing_the_manifest">10. WRITING THE MANIFEST</a></span></dt><dt><span class="section"><a href="#_singleton_one_instance_only">11. SINGLETON - ONE INSTANCE ONLY</a></span></dt><dt><span class="section"><a href="#_the_type_explorers">12. THE TYPE EXPLORERS</a></span></dt><dt><span class="section"><a href="#_writing_the_gencode_script">13. WRITING THE GENCODE SCRIPT</a></span></dt><dt><span class="section"><a href="#_hints_for_typewriters">14. HINTS FOR TYPEWRITERS</a></span></dt><dt><span class="section"><a href="#_how_to_include_a_type_into_upstream_cdist">15. HOW TO INCLUDE A TYPE INTO UPSTREAM CDIST</a></span></dt><dt><span class="section"><a href="#_see_also">16. SEE ALSO</a></span></dt><dt><span class="section"><a href="#_copying">17. COPYING</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_name"></a>1. NAME</h2></div></div></div><p>cdist-type - Functionality bundled</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_synopsis"></a>2. SYNOPSIS</h2></div></div></div><p>__TYPE ID --parameter value [--parameter value …]</p><p>__TYPE --parameter value [--parameter value …] (for singletons)</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_description"></a>3. DESCRIPTION</h2></div></div></div><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_how_to_use_a_type"></a>4. HOW TO USE A TYPE</h2></div></div></div><p>You can use types from the initial manifest or the type manifest like a
|
||
normal command:</p><pre class="screen"># Creates empty file /etc/cdist-configured
|
||
__file /etc/cdist-configured --type file
|
||
|
||
# Ensure tree is installed
|
||
__package tree --state installed</pre><p>A list of supported types can be found in the cdist-reference(7) manpage.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_singleton_types"></a>5. SINGLETON TYPES</h2></div></div></div><p>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.</p><p>Example:</p><pre class="screen"># __issue type manages /etc/issue
|
||
__issue
|
||
|
||
# Probably your own type - singletons may use parameters
|
||
__myfancysingleton --colour green</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_how_to_write_a_new_type"></a>6. HOW TO WRITE A NEW TYPE</h2></div></div></div><p>A type consists of</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
|
||
parameter (optional)
|
||
</li><li class="listitem">
|
||
manifest (optional)
|
||
</li><li class="listitem">
|
||
singleton (optional)
|
||
</li><li class="listitem">
|
||
explorer (optional)
|
||
</li><li class="listitem">
|
||
gencode (optional)
|
||
</li></ul></div><p>Types are stored below cdist/conf/type/. Their name should always be prefixed with
|
||
two underscores (__) to prevent collisions with other executables in $PATH.</p><p>To implement a new type, create the directory <span class="strong"><strong>cdist/conf/type/__NAME</strong></span>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_defining_parameters"></a>7. DEFINING PARAMETERS</h2></div></div></div><p>Every type consists of required, optional and boolean parameters, which must
|
||
each be declared in a newline separated file in <span class="strong"><strong><span class="strong"><strong>parameter/required</strong></span></strong></span>,
|
||
<span class="strong"><strong><span class="strong"><strong>parameter/required_multiple</strong></span></strong></span>, <span class="strong"><strong><span class="strong"><strong>parameter/optional</strong></span></strong></span>,
|
||
<span class="strong"><strong><span class="strong"><strong>parameter/optional_multiple</strong></span></strong></span> and <span class="strong"><strong><span class="strong"><strong>parameter/boolean</strong></span></strong></span>.
|
||
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.</p><p>Default values for optional parameters can be predefined in
|
||
<span class="strong"><strong><span class="strong"><strong>parameter/default/<name></strong></span></strong></span>.</p><p>Example:</p><pre class="screen">echo servername >> cdist/conf/type/__nginx_vhost/parameter/required
|
||
echo logdirectory >> cdist/conf/type/__nginx_vhost/parameter/optional
|
||
echo loglevel >> cdist/conf/type/__nginx_vhost/parameter/optional
|
||
mkdir cdist/conf/type/__nginx_vhost/parameter/default
|
||
echo warning > cdist/conf/type/__nginx_vhost/parameter/default/loglevel
|
||
echo server_alias >> cdist/conf/type/__nginx_vhost/parameter/optional_multiple
|
||
echo use_ssl >> cdist/conf/type/__nginx_vhost/parameter/boolean</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_using_parameters"></a>8. USING PARAMETERS</h2></div></div></div><p>The parameters given to a type can be accessed and used in all type scripts
|
||
(e.g manifest, gencode-<span class="strong"><strong>, explorer/</strong></span>). Note that boolean parameters are
|
||
represented by file existence. File exists → True,
|
||
file does not exist → False</p><p>Example: (e.g. in cdist/conf/type/__nginx_vhost/manifest)</p><pre class="screen"># required parameter
|
||
servername="$(cat "$__object/parameter/servername")"
|
||
|
||
# optional parameter
|
||
if [ -f "$__object/parameter/logdirectory" ]; then
|
||
logdirectory="$(cat "$__object/parameter/logdirectory")"
|
||
fi
|
||
|
||
# optional parameter with predefined default
|
||
loglevel="$(cat "$__object/parameter/loglevel")"
|
||
|
||
# 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</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_input_from_stdin"></a>9. INPUT FROM STDIN</h2></div></div></div><p>Every type can access what has been written on stdin when it has been called.
|
||
The result is saved into the <span class="strong"><strong><span class="strong"><strong>stdin</strong></span></strong></span> file in the object directory.</p><p>Example use of a type: (e.g. in cdist/conf/type/__archlinux_hostname)</p><pre class="screen">__file /etc/rc.conf --source - << eof
|
||
...
|
||
HOSTNAME="$__target_host"
|
||
...
|
||
eof</pre><p>If you have not seen this syntax (<< eof) before, it may help you to read
|
||
about "here documents".</p><p>In the __file type, stdin is used as source for the file, if - is used for source:</p><pre class="screen"> if [ -f "$__object/parameter/source" ]; then
|
||
source="$(cat "$__object/parameter/source")"
|
||
if [ "$source" = "-" ]; then
|
||
source="$__object/stdin"
|
||
fi
|
||
....</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_writing_the_manifest"></a>10. WRITING THE MANIFEST</h2></div></div></div><p>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:</p><pre class="screen">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 "$@"</pre><p>As you can see, the type can reference different environment variables,
|
||
which are documented in cdist-reference(7).</p><p>Always ensure the manifest is executable, otherwise cdist will not be able
|
||
to execute it. For more information about manifests see cdist-manifest(7).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_singleton_one_instance_only"></a>11. SINGLETON - ONE INSTANCE ONLY</h2></div></div></div><p>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:</p><pre class="screen">touch cdist/conf/type/__NAME/singleton</pre><p>This will also change the way your type must be called:</p><pre class="screen">__YOURTYPE --parameter value</pre><p>As you can see, the object ID is omitted, because it does not make any sense,
|
||
if your type can be used only once.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_the_type_explorers"></a>12. THE TYPE EXPLORERS</h2></div></div></div><p>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.</p><p>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):</p><pre class="screen">if [ -f "$__object/parameter/destination" ]; then
|
||
destination="$(cat "$__object/parameter/destination")"
|
||
else
|
||
destination="/$__object_id"
|
||
fi
|
||
|
||
if [ -e "$destination" ]; then
|
||
md5sum < "$destination"
|
||
fi</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_writing_the_gencode_script"></a>13. WRITING THE GENCODE SCRIPT</h2></div></div></div><p>There are two gencode scripts: <span class="strong"><strong><span class="strong"><strong>gencode-local</strong></span></strong></span> and <span class="strong"><strong><span class="strong"><strong>gencode-remote</strong></span></strong></span>.
|
||
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.</p><p>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:</p><pre class="screen"># 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"</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_hints_for_typewriters"></a>14. HINTS FOR TYPEWRITERS</h2></div></div></div><p>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.</p><p>If your type wants to save temporary data, that may be used by other types
|
||
later on (for instance <span class="emphasis"><em>file), you can save them in the subdirectory
|
||
"files" below $</em></span>object (but you must create it yourself).
|
||
cdist will not touch this directory.</p><p>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).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_how_to_include_a_type_into_upstream_cdist"></a>15. HOW TO INCLUDE A TYPE INTO UPSTREAM CDIST</h2></div></div></div><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_see_also"></a>16. SEE ALSO</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
|
||
cdist-explorer(7)
|
||
</li><li class="listitem">
|
||
cdist-hacker(7)
|
||
</li><li class="listitem">
|
||
cdist-stages(7)
|
||
</li><li class="listitem">
|
||
cdist-tutorial(7)
|
||
</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_copying"></a>17. COPYING</h2></div></div></div><p>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).</p></div></div></body></html> |