Merge pull request #335 from tpo/master

trivial docu fixes
This commit is contained in:
Nico Schottelius 2014-05-04 08:38:54 +02:00
commit 2c54e91df1
5 changed files with 48 additions and 25 deletions

View file

@ -20,6 +20,13 @@
A2XM=a2x -f manpage --no-xmllint -a encoding=UTF-8 A2XM=a2x -f manpage --no-xmllint -a encoding=UTF-8
A2XH=a2x -f xhtml --no-xmllint -a encoding=UTF-8 A2XH=a2x -f xhtml --no-xmllint -a encoding=UTF-8
# Create cross-links in html man pages
# We look for something like "cdist-type(7)" and make a href out of it
# The first matching group is the man page name and the second group
# is the man page section (1 or 7). The first three lines of the input
# (xml, DOCTYPE, head tags) are ignored, since the head tags contains
# the title of the page and should not contain a href.
CROSSLINK=sed --in-place '1,3!s/\([[:alnum:]_-]*\)(\([17]\))/<a href="..\/man\2\/\1.html">&<\/a>/g'
helper=./bin/build-helper helper=./bin/build-helper
MANDIR=docs/man MANDIR=docs/man
@ -86,6 +93,7 @@ MANSTATICALL=$(MANSTATICMAN) $(MANSTATICHTML)
# Creating the type html page # Creating the type html page
%.html: %.text %.html: %.text
$(A2XH) $^ $(A2XH) $^
$(CROSSLINK) $@
man: $(MANTYPEALL) $(MANREFALL) $(MANSTATICALL) man: $(MANTYPEALL) $(MANREFALL) $(MANSTATICALL)

View file

@ -26,7 +26,7 @@ cdist supports different subcommands as explained below.
GENERAL GENERAL
------- -------
All commands except the following options: All commands accept the following options:
-d, --debug:: -d, --debug::
Set log level to debug Set log level to debug
@ -34,7 +34,7 @@ All commands except the following options:
-h, --help:: -h, --help::
Show the help screen Show the help screen
-v, --verbose: -v, --verbose::
Set log level to info, be more verbose Set log level to info, be more verbose
-V, --version:: -V, --version::
@ -72,10 +72,10 @@ Configure one or more hosts
-s, --sequential:: -s, --sequential::
Operate on multiple hosts sequentially Operate on multiple hosts sequentially
--remote-copy REMOTE_COPY: --remote-copy REMOTE_COPY::
Command to use for remote copy (should behave like scp) Command to use for remote copy (should behave like scp)
--remote-exec REMOTE_EXEC: --remote-exec REMOTE_EXEC::
Command to use for remote execution (should behave like ssh) Command to use for remote execution (should behave like ssh)
SHELL SHELL

View file

@ -25,7 +25,7 @@ location.
For starters, having cdist (which includes the configuration database) on For starters, having cdist (which includes the configuration database) on
your notebook should be fine. your notebook should be fine.
Additionally an external copy of the git repository the configuration Additionally an external copy of the git repository the configuration
relies in is recommended, for use as backup as well to allow easy collaboration relies on is recommended, for use as backup as well as to allow easy collaboration
with others. with others.
For more sophisticated setups developing cdist configurations with multiple For more sophisticated setups developing cdist configurations with multiple

View file

@ -13,7 +13,7 @@ DESCRIPTION
Manifests are used to define which objects to create. Manifests are used to define which objects to create.
Objects are instances of **types**, like in object oriented programming languages. Objects are instances of **types**, like in object oriented programming languages.
An object is represented by the combination of An object is represented by the combination of
**type + slash + object name**: **__file/etc/cdist-configured** is an **type + slash + object name**: **\__file/etc/cdist-configured** is an
object of the type ***__file*** with the name ***etc/cdist-configured***. object of the type ***__file*** with the name ***etc/cdist-configured***.
All available types can be found in the **cdist/conf/type/** directory, All available types can be found in the **cdist/conf/type/** directory,
@ -89,7 +89,7 @@ SPLITTING UP THE INITIAL MANIFEST
--------------------------------- ---------------------------------
If you want to split up your initial manifest, you can create other shell If you want to split up your initial manifest, you can create other shell
scripts in **cdist/conf/manifest/** and include them in **cdist/conf/manifest/init**. scripts in **cdist/conf/manifest/** and include them in **cdist/conf/manifest/init**.
Cdist provides the environment variable ***__manifest*** to reference to Cdist provides the environment variable ***__manifest*** to reference
the directory containing the initial manifest (see cdist-reference(7)). the directory containing the initial manifest (see cdist-reference(7)).
The following example would include every file with a **.sh** suffix: The following example would include every file with a **.sh** suffix:
@ -110,24 +110,39 @@ setup the variable "require" to contain the requirements. Multiple
requirements can be added white space separated. requirements can be added white space separated.
-------------------------------------------------------------------------------- --------------------------------------------------------------------------------
# No dependency 1 # No dependency
__file /etc/cdist-configured 2 __file /etc/cdist-configured
3
# Require above object 4 # Require above object
require="__file/etc/cdist-configured" __link /tmp/cdist-testfile \ 5 require="__file/etc/cdist-configured" __link /tmp/cdist-testfile \
--source /etc/cdist-configured --type symbolic 6 --source /etc/cdist-configured --type symbolic
7
# Require two objects 8 # Require two objects
require="__file/etc/cdist-configured __link/tmp/cdist-testfile" \ 9 require="__file/etc/cdist-configured __link/tmp/cdist-testfile" \
__file /tmp/cdist-another-testfile 10 __file /tmp/cdist-another-testfile
-------------------------------------------------------------------------------- --------------------------------------------------------------------------------
Above the "require" variable is only set for the command that is
immediately following it. Dependencies should allways be declared that way.
On line 4 you can see that the instantion of a type "__link" object needs
the object "__file/etc/cdist-configured" to be present, before it can proceed.
This also means that the "__link" command must make sure, that either
"__file/etc/cdist-configured" allready is present, or, if it's not, it needs
to be created. The task of cdist is to make sure, that the dependency will be
resolved appropriately and thus "__file/etc/cdist-configured" be created
if necessary before "__link" proceeds (or to abort execution with an error).
All objects that are created in a type manifest are automatically required All objects that are created in a type manifest are automatically required
from the type that is calling them. This is called "autorequirement" in from the type that is calling them. This is called "autorequirement" in
cdist jargon. cdist jargon.
You can find an more in depth description of the flow execution of manifests
in cdist-stages(7) and of how types work in cdist-type(7).
CREATE DEPENDENCIES FROM EXECUTION ORDER CREATE DEPENDENCIES FROM EXECUTION ORDER
----------------------------------------- -----------------------------------------
You can tell cdist to execute all types in the order in which they are created You can tell cdist to execute all types in the order in which they are created
@ -149,10 +164,10 @@ If you whish, you can setup the environment variable CDIST_OVERRIDE
(any value or even empty is ok) to tell cdist, that this object override is (any value or even empty is ok) to tell cdist, that this object override is
wanted and should be accepted. wanted and should be accepted.
ATTENTION: Only use this feature if you are 100% sure in which order ATTENTION: Only use this feature if you are 100% sure in which order
cdist encounter the affected objects, otherwhise this results cdist encounters the affected objects, otherwhise this results
into an undefined situation. in an undefined situation.
If CDIST_OVERRIDE and CDIST_ORDER_DEPENDENCY is set for an object, If CDIST_OVERRIDE and CDIST_ORDER_DEPENDENCY are set for an object,
CDIST_ORDER_DEPENDENCY will be ignored, because adding a dependency in case of CDIST_ORDER_DEPENDENCY will be ignored, because adding a dependency in case of
overrides would result in circular dependencies, which is an error. overrides would result in circular dependencies, which is an error.
@ -198,7 +213,7 @@ How to override objects:
-------------------------------------------------------------------------------- --------------------------------------------------------------------------------
# for example in the inital manifest # for example in the inital manifest
# reate user account foobar with some hash for password # create user account foobar with some hash for password
__user foobar --password 'some_fancy_hash' --home /home/foobarexample __user foobar --password 'some_fancy_hash' --home /home/foobarexample
# ... many statements and includes in the manifest later ... # ... many statements and includes in the manifest later ...
@ -210,8 +225,8 @@ __user foobar --password 'some_other_hash'
# this tells cdist, that you know that this is an override and should be accepted # this tells cdist, that you know that this is an override and should be accepted
CDIST_OVERRIDE=yes __user foobar --password 'some_other_hash' CDIST_OVERRIDE=yes __user foobar --password 'some_other_hash'
# its only an override, means the parameter --home is not touched # it's only an override, means the parameter --home is not touched
# and stay at the original value of /home/foobarexample # and stays at the original value of /home/foobarexample
-------------------------------------------------------------------------------- --------------------------------------------------------------------------------
Dependencies defined by execution order work as following: Dependencies defined by execution order work as following:

View file

@ -25,7 +25,7 @@ to use.
HOW TO USE A TYPE HOW TO USE A TYPE
----------------- -----------------
You can use types from the initial manifest or the type manifest like a You can use types from the initial manifest or the type manifest like a
normal command: normal shell command:
-------------------------------------------------------------------------------- --------------------------------------------------------------------------------
# Creates empty file /etc/cdist-configured # Creates empty file /etc/cdist-configured