90 lines
12 KiB
HTML
90 lines
12 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.76.1" /></head><body><div xml:lang="en" class="article" title="cdist-type(7)" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="idp25203744"></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><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="#_writing_the_manifest">8. WRITING THE MANIFEST</a></span></dt><dt><span class="section"><a href="#_singleton_only_instance_only">9. SINGLETON - ONLY INSTANCE ONLY</a></span></dt><dt><span class="section"><a href="#_the_type_explorers">10. THE TYPE EXPLORERS</a></span></dt><dt><span class="section"><a href="#_writing_the_gencode_script">11. WRITING THE GENCODE SCRIPT</a></span></dt><dt><span class="section"><a href="#_hints_for_typewriters">12. HINTS FOR TYPEWRITERS</a></span></dt><dt><span class="section"><a href="#_how_to_include_a_type_into_upstream_cdist">13. HOW TO INCLUDE A TYPE INTO UPSTREAM CDIST</a></span></dt><dt><span class="section"><a href="#_see_also">14. SEE ALSO</a></span></dt><dt><span class="section"><a href="#_copying">15. COPYING</a></span></dt></dl></div><div class="section" title="1. NAME"><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" title="2. SYNOPSIS"><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" title="3. DESCRIPTION"><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" title="4. HOW TO USE A TYPE"><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" title="5. SINGLETON TYPES"><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" title="6. HOW TO WRITE A NEW TYPE"><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" 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 conf/type/. Their name should always be prefixed with
|
|||
|
two underscores (__) to prevent collisions with other executables in $PATH.</p><p>To begin a new type, just create the directory <span class="strong"><strong>conf/type/__NAME</strong></span>.</p></div><div class="section" title="7. DEFINING PARAMETERS"><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 optional and required parameters, which must
|
|||
|
be created in a newline seperated file in <span class="strong"><strong><span class="strong"><strong>parameters/required</strong></span></strong></span> and
|
|||
|
<span class="strong"><strong><span class="strong"><strong>parameters/optional</strong></span></strong></span>. If either or both missing, the type will have
|
|||
|
no required, no optional or no parameters at all.</p><p>Example:</p><pre class="screen">echo servername >> conf/type/__nginx_vhost/parameter/required
|
|||
|
echo logdirectory >> conf/type/__nginx_vhost/parameter/optional</pre></div><div class="section" title="8. WRITING THE MANIFEST"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_writing_the_manifest"></a>8. 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" title="9. SINGLETON - ONLY INSTANCE ONLY"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_singleton_only_instance_only"></a>9. SINGLETON - ONLY 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 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" title="10. THE TYPE EXPLORERS"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_the_type_explorers"></a>10. 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" title="11. WRITING THE GENCODE SCRIPT"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_writing_the_gencode_script"></a>11. 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.</p><p>The gencode scripts can make use of the parameters, the global explorers
|
|||
|
and the type specific explorers. The output (stdout) of these script is
|
|||
|
saved by cdist and will be executed on the target.</p><p>If the gencode scripts encounter 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" title="12. HINTS FOR TYPEWRITERS"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_hints_for_typewriters"></a>12. 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" title="13. HOW TO INCLUDE A TYPE INTO UPSTREAM CDIST"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_how_to_include_a_type_into_upstream_cdist"></a>13. 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 submit the git url containing the type for
|
|||
|
inclusion to the mailinglist <span class="strong"><strong>cdist at cdist — at — l.schottelius.org</strong></span>
|
|||
|
or open a pull request at <a class="ulink" href="http://github.com/telmich/cdist" target="_top">http://github.com/telmich/cdist</a>.</p><p>Ensure a corresponding manpage named man.text in asciidoc format with
|
|||
|
the manpage-name "cdist-type__NAME" is included in the type directory.</p></div><div class="section" title="14. SEE ALSO"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_see_also"></a>14. SEE ALSO</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
|
|||
|
cdist-explorer(7)
|
|||
|
</li><li class="listitem">
|
|||
|
cdist-stages(7)
|
|||
|
</li><li class="listitem">
|
|||
|
cdist-tutorial(7)
|
|||
|
</li></ul></div></div><div class="section" title="15. COPYING"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_copying"></a>15. 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>
|