forked from ungleich-public/cdist
cleanup cdist-type
Signed-off-by: Nico Schottelius <nico@brief.schottelius.org>
This commit is contained in:
parent
5e00ac702a
commit
3d8f26b42a
2 changed files with 28 additions and 46 deletions
|
@ -28,31 +28,6 @@ cdist-manifest::
|
||||||
cdist-type::
|
cdist-type::
|
||||||
Understand how types are working and created [intermediate]
|
Understand how types are working and created [intermediate]
|
||||||
|
|
||||||
CREATING YOUR FIRST OWN TYPE
|
|
||||||
----------------------------
|
|
||||||
=> short example, reference to cdist-type(7)!
|
|
||||||
=> motivation
|
|
||||||
|
|
||||||
Use a type to bundle functionalitY
|
|
||||||
|
|
||||||
<with object id? or signleton here already>
|
|
||||||
|
|
||||||
Debug with var - can be used by yourself
|
|
||||||
__debug::
|
|
||||||
If this variable is setup, cdist runs in debug mode.
|
|
||||||
You can use this information, to only output stuff in debug
|
|
||||||
mode as well.
|
|
||||||
Available for: initial manifest, type manifest, gencode, code
|
|
||||||
|
|
||||||
|
|
||||||
USING EXPLORERS
|
|
||||||
---------------
|
|
||||||
cdist-explorer.text
|
|
||||||
|
|
||||||
DEBUGGING YOUR TYPES
|
|
||||||
--------------------
|
|
||||||
|
|
||||||
|
|
||||||
cdist-best-practice::
|
cdist-best-practice::
|
||||||
Hints from real life experience to help you to organise cdist [intermediate]
|
Hints from real life experience to help you to organise cdist [intermediate]
|
||||||
|
|
||||||
|
|
|
@ -37,11 +37,12 @@ __package tree --state installed
|
||||||
|
|
||||||
A list of supported types can be found in the cdist-reference(7) manpage.
|
A list of supported types can be found in the cdist-reference(7) manpage.
|
||||||
|
|
||||||
|
|
||||||
SINGLETON TYPES
|
SINGLETON TYPES
|
||||||
---------------
|
---------------
|
||||||
If a type is flagged as a singleton, it may me used only once. This
|
If a type is flagged as a singleton, it may be used only
|
||||||
is useful for types which can be used only once on a system. If a type
|
once per host. This is useful for types which can be used only once on a
|
||||||
can only be used once, it does not take an
|
system. Singleton types do not take an object name as argument.
|
||||||
|
|
||||||
Example:
|
Example:
|
||||||
--------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------
|
||||||
|
@ -53,7 +54,6 @@ __myfancysingleton --colour green
|
||||||
--------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
HOW TO WRITE A NEW TYPE
|
HOW TO WRITE A NEW TYPE
|
||||||
-----------------------
|
-----------------------
|
||||||
A type consists of
|
A type consists of
|
||||||
|
@ -65,17 +65,16 @@ A type consists of
|
||||||
- gencode (optional)
|
- gencode (optional)
|
||||||
|
|
||||||
Types are stored below conf/type/. Their name should always be prefixed with
|
Types are stored below conf/type/. Their name should always be prefixed with
|
||||||
two underscores (__) to prevent collisions with other binaries in $PATH.
|
two underscores (__) to prevent collisions with other executables in $PATH.
|
||||||
|
|
||||||
To begin a new type from a template, execute "cdist-type-template __NAME"
|
To begin a new type, just create the directory **conf/type/__NAME**.
|
||||||
and cd conf/type/__NAME.
|
|
||||||
|
|
||||||
|
|
||||||
DEFINING PARAMETERS
|
DEFINING PARAMETERS
|
||||||
-------------------
|
-------------------
|
||||||
Every type consists of optional and required parameters, which must
|
Every type consists of optional and required parameters, which must
|
||||||
be created in a newline seperated file in parameters/required and
|
be created in a newline seperated file in ***parameters/required*** and
|
||||||
parameters/optional. If either or both missing, the type will have
|
***parameters/optional***. If either or both missing, the type will have
|
||||||
no required, no optional or no parameters at all.
|
no required, no optional or no parameters at all.
|
||||||
|
|
||||||
Example:
|
Example:
|
||||||
|
@ -110,21 +109,27 @@ As you can see, the type can reference different environment variables,
|
||||||
which are documented in cdist-reference(7).
|
which are documented in cdist-reference(7).
|
||||||
|
|
||||||
Always ensure the manifest is executable, otherwise cdist will not be able
|
Always ensure the manifest is executable, otherwise cdist will not be able
|
||||||
to execute it.
|
to execute it. For more information about manifests see cdist-manifest(7).
|
||||||
|
|
||||||
|
|
||||||
SINGLETON - ONLY INSTANCE ONLY
|
SINGLETON - ONLY INSTANCE ONLY
|
||||||
------------------------------
|
------------------------------
|
||||||
If you want to ensure that a type can only be used once per target, you can
|
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
|
mark it as a singleton: Just create the (empty) file "singleton" in your type
|
||||||
directory. This will also change the way your type must be called:
|
directory:
|
||||||
|
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
touch conf/type/__NAME/singleton
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
This will also change the way your type must be called:
|
||||||
|
|
||||||
--------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------
|
||||||
__YOURTYPE --parameter value
|
__YOURTYPE --parameter value
|
||||||
--------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------
|
||||||
|
|
||||||
As you can see, the ID is omitted, because it does not make any sense, if your
|
As you can see, the object ID is omitted, because it does not make any sense,
|
||||||
type can be used only once.
|
if your type can be used only once.
|
||||||
|
|
||||||
|
|
||||||
THE TYPE EXPLORERS
|
THE TYPE EXPLORERS
|
||||||
|
@ -134,7 +139,7 @@ explorers, which will be executed on the target for every created object.
|
||||||
|
|
||||||
The explorers are stored under the "explorer" directory below the type.
|
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
|
It could for instance contain code to check the md5sum of a file on the
|
||||||
client, like this (shortened version from real type __file):
|
client, like this (shortened version from the type __file):
|
||||||
|
|
||||||
--------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------
|
||||||
if [ -f "$__object/parameter/destination" ]; then
|
if [ -f "$__object/parameter/destination" ]; then
|
||||||
|
@ -151,15 +156,15 @@ fi
|
||||||
|
|
||||||
WRITING THE GENCODE SCRIPT
|
WRITING THE GENCODE SCRIPT
|
||||||
--------------------------
|
--------------------------
|
||||||
There are two gencode scripts: gencode-local and gencode-remote.
|
There are two gencode scripts: ***gencode-local*** and ***gencode-remote***.
|
||||||
The output of gencode-local is executed locally, whereas
|
The output of gencode-local is executed locally, whereas
|
||||||
the output of gencode-remote is executed on the target.
|
the output of gencode-remote is executed on the target.
|
||||||
|
|
||||||
The gencode script can make use of the parameters, the global explorers
|
The gencode scripts can make use of the parameters, the global explorers
|
||||||
and the type specific explorers. The output (stdout) of this script is
|
and the type specific explorers. The output (stdout) of these script is
|
||||||
saved by cdist and will be executed on the target.
|
saved by cdist and will be executed on the target.
|
||||||
|
|
||||||
If the gencode script encounters an error, it should print diagnostic
|
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
|
messages to stderr and exit non-zero. If you need to debug the gencode
|
||||||
script, you can write to stderr:
|
script, you can write to stderr:
|
||||||
|
|
||||||
|
@ -181,13 +186,14 @@ type should create an object of the specific type.
|
||||||
|
|
||||||
If your type wants to save temporary data, that may be used by other types
|
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
|
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
|
"files" below $__object (but you must create it yourself).
|
||||||
this directory.
|
cdist will not touch this directory.
|
||||||
|
|
||||||
If your type contains static files, it's also recommended to place them in
|
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
|
a folder named "files" within the type (again, because cdist guarantees to
|
||||||
never ever touch this folder).
|
never ever touch this folder).
|
||||||
|
|
||||||
|
|
||||||
HOW TO INCLUDE A TYPE INTO UPSTREAM CDIST
|
HOW TO INCLUDE A TYPE INTO UPSTREAM CDIST
|
||||||
-----------------------------------------
|
-----------------------------------------
|
||||||
If you think your type may be useful for others, ensure it works with the
|
If you think your type may be useful for others, ensure it works with the
|
||||||
|
@ -203,9 +209,10 @@ SEE ALSO
|
||||||
--------
|
--------
|
||||||
- cdist-explorer(7)
|
- cdist-explorer(7)
|
||||||
- cdist-stages(7)
|
- cdist-stages(7)
|
||||||
|
- cdist-tutorial(7)
|
||||||
|
|
||||||
|
|
||||||
COPYING
|
COPYING
|
||||||
-------
|
-------
|
||||||
Copyright \(C) 2011 Nico Schottelius. Free use of this software is
|
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).
|
granted under the terms of the GNU General Public License version 3 (GPLv3).
|
||||||
|
|
Loading…
Reference in a new issue