tom/cdist
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Improve and fix reference doc and cdist man page.

Browse source
This commit is contained in:
Darko Poljak 2016-07-20 08:16:58 +02:00
commit 7e57575f9e
2 changed files with 55 additions and 45 deletions
Download patch file Download diff file Expand all files Collapse all files

59
docs/src/cdist-reference.rst.sh
View file

@ -56,19 +56,19 @@ cat << eof
Paths Paths
----- -----
\$HOME/.cdist \$HOME/.cdist
The standard cdist configuration directory relative to your home directory The standard cdist configuration directory relative to your home directory.
This is usually the place you want to store your site specific configuration This is usually the place you want to store your site specific configuration.
cdist/conf/ cdist/conf/
The distribution configuration directory The distribution configuration directory.
This contains types and explorers to be used This contains types and explorers to be used.
confdir confdir
Cdist will use all available configuration directories and create Cdist will use all available configuration directories and create
a temporary confdir containing links to the real configuration directories. a temporary confdir containing links to the real configuration directories.
This way it is possible to merge configuration directories. This way it is possible to merge configuration directories.
By default it consists of everything in \$HOME/.cdist and cdist/conf/. By default it consists of everything in \$HOME/.cdist and cdist/conf/.
For more details see cdist(1) For more details see cdist(1).
confdir/files/ confdir/files/
Cdist does not care about this directory besides providing access to it. Cdist does not care about this directory besides providing access to it.
@ -99,16 +99,16 @@ confdir/type/<name>/
This directory is referenced by the variable __type (see below). This directory is referenced by the variable __type (see below).
confdir/type/<name>/man.rst confdir/type/<name>/man.rst
Manpage in reStructuredText format (required for inclusion into upstream) Manpage in reStructuredText format (required for inclusion into upstream).
confdir/type/<name>/manifest confdir/type/<name>/manifest
Used to generate additional objects from a type. Used to generate additional objects from a type.
confdir/type/<name>/gencode-local confdir/type/<name>/gencode-local
Used to generate code to be executed on the source host Used to generate code to be executed on the source host.
confdir/type/<name>/gencode-remote confdir/type/<name>/gencode-remote
Used to generate code to be executed on the target host Used to generate code to be executed on the target host.
confdir/type/<name>/parameter/required confdir/type/<name>/parameter/required
Parameters required by type, \n separated list. Parameters required by type, \n separated list.
@ -184,7 +184,7 @@ files
(for instance to store template results). (for instance to store template results).
changed changed
This empty file exists in an object directory, if the object has This empty file exists in an object directory, if the object has
code to be executed (either remote or local) code to be executed (either remote or local).
stdin stdin
This file exists and contains data, if data was provided on stdin This file exists and contains data, if data was provided on stdin
when the type was called. when the type was called.
@ -196,67 +196,70 @@ The following environment variables are exported by cdist:
__explorer __explorer
Directory that contains all global explorers. Directory that contains all global explorers.
Available for: initial manifest, explorer, type explorer, shell Available for: initial manifest, explorer, type explorer, shell.
__files __files
Directory that contains content from the "files" subdirectories Directory that contains content from the "files" subdirectories
from the configuration directories. from the configuration directories.
Available for: initial manifest, type manifest, type gencode, shell Available for: initial manifest, type manifest, type gencode, shell.
__manifest __manifest
Directory that contains the initial manifest. Directory that contains the initial manifest.
Available for: initial manifest, type manifest, shell Available for: initial manifest, type manifest, shell.
__global __global
Directory that contains generic output like explorer. Directory that contains generic output like explorer.
Available for: initial manifest, type manifest, type gencode, shell Available for: initial manifest, type manifest, type gencode, shell.
__messages_in __messages_in
File to read messages from. File to read messages from.
Available for: initial manifest, type manifest, type gencode Available for: initial manifest, type manifest, type gencode.
__messages_out __messages_out
File to write messages. File to write messages.
Available for: initial manifest, type manifest, type gencode Available for: initial manifest, type manifest, type gencode.
__object __object
Directory that contains the current object. Directory that contains the current object.
Available for: type manifest, type explorer, type gencode and code scripts Available for: type manifest, type explorer, type gencode and code scripts.
__object_id __object_id
The type unique object id. The type unique object id.
Available for: type manifest, type explorer, type gencode and code scripts Available for: type manifest, type explorer, type gencode and code scripts.
Note: The leading and the trailing "/" will always be stripped (caused by Note: The leading and the trailing "/" will always be stripped (caused by
the filesystem database and ensured by the core). the filesystem database and ensured by the core).
Note: Double slashes ("//") will not be fixed and result in an error. Note: Double slashes ("//") will not be fixed and result in an error.
__object_name __object_name
The full qualified name of the current object. The full qualified name of the current object.
Available for: type manifest, type explorer, type gencode Available for: type manifest, type explorer, type gencode.
__target_host __target_host
The host we are deploying to. The host we are deploying to.
Available for: explorer, initial manifest, type explorer, type manifest, type gencode, shell Available for: explorer, initial manifest, type explorer, type manifest, type gencode, shell.
__type __type
Path to the current type. Path to the current type.
Available for: type manifest, type gencode Available for: type manifest, type gencode.
__type_explorer __type_explorer
Directory that contains the type explorers. Directory that contains the type explorers.
Available for: type explorer Available for: type explorer.
Environment variables (for writing) Environment variables (for writing)
----------------------------------- -----------------------------------
The following environment variables influence the behaviour of cdist: The following environment variables influence the behaviour of cdist:
require require
Setup dependencies between objects (see \`cdist manifest <cdist-manifest.html>\`_) Setup dependencies between objects (see \`cdist manifest <cdist-manifest.html>\`_).
CDIST_PATH
Colon delimited list of config directories.
CDIST_LOCAL_SHELL CDIST_LOCAL_SHELL
Use this shell locally instead of /bin/sh to execute scripts Use this shell locally instead of /bin/sh to execute scripts.
CDIST_REMOTE_SHELL CDIST_REMOTE_SHELL
Use this shell remotely instead of /bin/sh to execute scripts Use this shell remotely instead of /bin/sh to execute scripts.
CDIST_OVERRIDE CDIST_OVERRIDE
Allow overwriting type parameters (see \`cdist manifest <cdist-manifest.html>\`_) Allow overwriting type parameters (see \`cdist manifest <cdist-manifest.html>\`_).
CDIST_ORDER_DEPENDENCY CDIST_ORDER_DEPENDENCY
Create dependencies based on the execution order (see \`cdist manifest <cdist-manifest.html>\`_) Create dependencies based on the execution order (see \`cdist manifest <cdist-manifest.html>\`_).
CDIST_REMOTE_EXEC CDIST_REMOTE_EXEC
Use this command for remote execution (should behave like ssh) Use this command for remote execution (should behave like ssh).
CDIST_REMOTE_COPY CDIST_REMOTE_COPY
Use this command for remote copy (should behave like scp) Use this command for remote copy (should behave like scp).
eof eof

41
docs/src/man1/cdist.rst
View file

@ -23,7 +23,10 @@ SYNOPSIS
DESCRIPTION DESCRIPTION
----------- -----------
cdist is the frontend executable to the cdist configuration management. cdist is the frontend executable to the cdist configuration management.
cdist supports different subcommands as explained below. It supports different subcommands as explained below.
It is written in Python so it requires :strong:`python`\ (1) to be installed.
It requires a minimal Python version 3.2.
GENERAL GENERAL
------- -------
@ -54,7 +57,7 @@ cdist posters - a must have for every office.
CONFIG CONFIG
------ ------
Configure one or more hosts Configure one or more hosts.
.. option:: -c CONF_DIR, --conf-dir CONF_DIR .. option:: -c CONF_DIR, --conf-dir CONF_DIR
@ -110,13 +113,9 @@ FILES
~/.cdist ~/.cdist
Your personal cdist config directory. If exists it will be Your personal cdist config directory. If exists it will be
automatically used. automatically used.
${cdist_prefix}/cdist/conf cdist/conf
The distribution configuration directory. ${cdist_prefix} is The distribution configuration directory. It contains official types and
installation-dependent. If you install cdist using git it is explorers. This path is relative to cdist installation directory.
equal to your cloned directory. If you install it using python
pip then it is equal to
${prefix}/lib/python<version>/site-packages/cdist sub-directory
where ${prefix}, by default, is /usr/local (see :strong:`python`\ (1)).
EXAMPLES EXAMPLES
-------- --------
@ -162,26 +161,34 @@ TMPDIR, TEMP, TMP
more information. This is rather useful, if the standard more information. This is rather useful, if the standard
directory used does not allow executables. directory used does not allow executables.
CDIST_PATH
Colon delimited list of config directories.
CDIST_LOCAL_SHELL CDIST_LOCAL_SHELL
Selects shell for local script execution, defaults to /bin/sh Selects shell for local script execution, defaults to /bin/sh.
CDIST_REMOTE_SHELL CDIST_REMOTE_SHELL
Selects shell for remote scirpt execution, defaults to /bin/sh Selects shell for remote scirpt execution, defaults to /bin/sh.
CDIST_OVERRIDE
Allow overwriting type parameters.
CDIST_ORDER_DEPENDENCY
Create dependencies based on the execution order.
CDIST_REMOTE_EXEC CDIST_REMOTE_EXEC
Use this command for remote execution (should behave like ssh) Use this command for remote execution (should behave like ssh).
CDIST_REMOTE_COPY CDIST_REMOTE_COPY
Use this command for remote copy (should behave like scp) Use this command for remote copy (should behave like scp).
EXIT STATUS EXIT STATUS
----------- -----------
The following exit values shall be returned: The following exit values shall be returned:
0 0 Successful completion.
Successful completion
1 1 One or more host configurations failed.
One or more host configurations failed
AUTHORS AUTHORS