Merge pull request #538 from mhameed/master

Documentation fixes
This commit is contained in:
Darko Poljak 2017-07-01 09:19:24 +02:00 committed by GitHub
commit b61d82debb
9 changed files with 37 additions and 37 deletions

View file

@ -97,7 +97,7 @@ Including a possible common base that is reused across the different sites::
git merge common
The following **.git/config** is taken from a a real world scenario::
The following **.git/config** is taken from a real world scenario:
# Track upstream, merge from time to time
[remote "upstream"]
@ -142,7 +142,7 @@ implement this scenario with a gateway host and sudo:
- Setup the ssh-pubkey for this user that has the right to configure all hosts
- Create a wrapper to update the cdist configuration in ~cdist/cdist
- Allow every developer to execute this script via sudo as the user cdist
- Allow run of cdist as user cdist on specific hosts on a per user/group base
- Allow run of cdist as user cdist on specific hosts on a per user/group basis.
- f.i. nico ALL=(ALL) NOPASSWD: /home/cdist/bin/cdist config hostabc
@ -171,7 +171,7 @@ Templating
}
EOF
* in the manifest, export the relevant variables and add the following lines in your manifest:
* in the manifest, export the relevant variables and add the following lines to your manifest:
.. code-block:: console
@ -213,11 +213,11 @@ Other content in cdist repository
Usually the cdist repository contains all configuration
items. Sometimes you may have additional resources that
you would like to store in your central configuration
repositiory (like password files from KeepassX,
repository (like password files from KeepassX,
Libreoffice diagrams, etc.).
It is recommended to use a subfolder named "non-cdist"
in the repository for such content: It allows you to
easily distinguish what is used by cdist and what not
easily distinguish what is used by cdist and what is not
and also to store all important files in one
repository.

View file

@ -3,8 +3,8 @@ Explorer
Description
-----------
Explorer are small shell scripts, which will be executed on the target
host. The aim of the explorer is to give hints to types on how to act on the
Explorers are small shell scripts, which will be executed on the target
host. The aim of each explorer is to give hints to types on how to act on the
target system. An explorer outputs the result to stdout, which is usually
a one liner, but may be empty or multi line especially in the case of
type explorers.

View file

@ -8,7 +8,7 @@ Simplicity
Design
+ Type and core cleanly separated
+ Sticks completly to the KISS (keep it simple and stupid) paradigma
+ Sticks completely to the KISS (keep it simple and stupid) paradigm
+ Meaningful error messages - do not lose time debugging error messages
+ Consistency in behaviour, naming and documentation
+ No surprise factor: Only do what is obviously clear, no magic
@ -40,9 +40,9 @@ Requirements, Simplicity
UNIX
Reuse of existing tools like cat, find, mv, ...
UNIX, familar environment, documentation
UNIX, familiar environment, documentation
Is available as manpages and HTML
UNIX, simplicity, familar environment
UNIX, simplicity, familiar environment
cdist is configured in POSIX shell

View file

@ -4,7 +4,7 @@ Hacking
Welcome
-------
Welcome dear hacker! I invite you to a tour of pointers to
get into the usable configuration mangament system, cdist.
get into the usable configuration management system, cdist.
The first thing to know is probably that cdist is brought to
you by people who care about how code looks like and who think
@ -21,18 +21,18 @@ subject prefixed with "[BUG] " or create an issue on github.
Coding conventions (everywhere)
-------------------------------
If something should be better done or needs to fixed, add the word FIXME
If something should be improved or needs to be fixed, add the word FIXME
nearby, so grepping for FIXME gives all positions that need to be fixed.
Indention is 4 spaces (welcome to the python world).
Indentation is 4 spaces (welcome to the python world).
How to submit stuff for inclusion into upstream cdist
-----------------------------------------------------
If you did some cool changes to cdist, which you value as a benefit for
everybody using cdist, you're welcome to propose inclusion into upstream.
If you did some cool changes to cdist, which you think might be of benefit to other
cdist users, you're welcome to propose inclusion into upstream.
There are though some requirements to ensure your changes don't break others
There are some requirements to ensure your changes don't break other peoples
work nor kill the authors brain:
- All files should contain the usual header (Author, Copying, etc.)
@ -130,7 +130,7 @@ use **git stash** to stash your changes away::
git fetch -v origin
git merge origin/master
Similar when you want to develop another new feature, you go back
Similarly when you want to develop another new feature, you go back
to the master branch and create another branch based on it::
.. code-block:: sh

View file

@ -7,7 +7,7 @@ Requirements
Source Host
~~~~~~~~~~~
This is the machine you use to configure the target hosts.
This is the machine from which you will configure target hosts.
* /bin/sh: A posix like shell (for instance bash, dash, zsh)
* Python >= 3.2

View file

@ -51,7 +51,7 @@ The **initial manifest** is the entry point for cdist to find out, which
**objects** to configure on the selected host.
Cdist expects the initial manifest at **cdist/conf/manifest/init**.
Within this initial manifest you define, which objects should be
Within this initial manifest you define which objects should be
created on which host. To distinguish between hosts, you can use the
environment variable **__target_host** and/or **__target_hostname** and/or
**__target_fqdn**. Let's have a look at a simple example::
@ -114,7 +114,7 @@ requirements can be added white space separated.
Above the "require" variable is only set for the command that is
immediately following it. Dependencies should always be declared that way.
On line 4 you can see that the instantion of a type "\__link" object needs
On line 4 you can see that the instantiation 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
@ -149,7 +149,7 @@ All objects that are created in a type manifest are automatically required
from the type that is calling them. This is called "autorequirement" in
cdist jargon.
You can find an more in depth description of the flow execution of manifests
You can find a more in depth description of the flow execution of manifests
in `cdist execution stages <cdist-stages.html>`_ and of how types work in `cdist type <cdist-type.html>`_.

View file

@ -3,8 +3,7 @@ Execution stages
Description
-----------
Starting the execution of deployment with cdist, cdist passes
through different stages.
When cdist is started, it passes through different stages.
Stage 1: target information retrieval
@ -67,5 +66,5 @@ The cache stores the information from the current run for later use.
Summary
-------
If, and only if, all the stages complete without an errors, the configuration
If, and only if, all the stages complete without errors, the configuration
will be applied to the target.

View file

@ -40,9 +40,9 @@ call cdist types, the result is always the same.
Zero dependency configuration management
----------------------------------------
Cdist requires very litte on a target system. Even better,
Cdist requires very little on a target system. Even better,
in almost all cases all dependencies are usually fulfilled.
Cdist does not require an agent or a high level programming
Cdist does not require an agent or high level programming
languages on the target host: it will run on any host that
has a **ssh server running** and a posix compatible shell
(**/bin/sh**). Compared to other configuration management systems,
@ -52,7 +52,7 @@ Push based distribution
-----------------------
Cdist uses the push based model for configuration. In this
scenario, one (or more) computers connect the target hosts
scenario, one (or more) computers connect to the target hosts
and apply the configuration. That way the source host has
very little requirements: Cdist can even run on a sysadmin
notebook that is loosely connected to the network and has

View file

@ -72,7 +72,7 @@ Configure/install one or more hosts.
.. option:: -b, --beta
Enable beta functionalities.
Enable beta functionality.
Can also be enabled using CDIST_BETA env var.
@ -88,8 +88,8 @@ Configure/install one or more hosts.
.. option:: -f HOSTFILE, --file HOSTFILE
Read additional hosts to operate on from specified file
or from stdin if '-' (each host on separate line).
Read specified file for a list of additional hosts to operate on
or if '-' is given, read stdin (one host per line).
If no host or host file is specified then, by default,
read hosts from stdin. For the file format see below.
@ -134,12 +134,13 @@ Configure/install one or more hosts.
HOSTFILE FORMAT
~~~~~~~~~~~~~~~
HOSTFILE contains hosts per line.
All characters after and including '#' until the end of line is a comment.
In a line, all leading and trailing whitespace characters are ignored.
The HOSTFILE contains one host per line.
A comment is started with '#' and continues to the end of the line.
Any leading and trailing whitespace on a line is ignored.
Empty lines are ignored/skipped.
Hostfile line is processed like the following. First, all comments are
The Hostfile lines are processed as follows. First, all comments are
removed. Then all leading and trailing whitespace characters are stripped.
If such a line results in empty line it is ignored/skipped. Otherwise,
host string is used.
@ -244,7 +245,7 @@ CDIST_REMOTE_COPY
Use this command for remote copy (should behave like scp).
CDIST_BETA
Enable beta functionalities.
Enable beta functionality.
EXIT STATUS
-----------
@ -275,10 +276,10 @@ options. For more details refer to :strong:`sshd_config`\ (5).
When requirements for the same object are defined in different manifests (see
example below), for example, in init manifest and in some other type manifest
and those requirements differ then dependency resolver cannot detect
dependencies right. This happens because cdist cannot prepare all objects first
dependencies correctly. This happens because cdist cannot prepare all objects first
and run all objects afterwards. Some object can depend on the result of type
explorer(s) and explorers are executed during object run. cdist will detect
such case and write warning message. Example for such a case:
such case and display a warning message. An example of such a case:
.. code-block:: sh