diff --git a/docs/src/cdist-best-practice.rst b/docs/src/cdist-best-practice.rst index 493f1506..fdbb7a80 100644 --- a/docs/src/cdist-best-practice.rst +++ b/docs/src/cdist-best-practice.rst @@ -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. diff --git a/docs/src/cdist-explorer.rst b/docs/src/cdist-explorer.rst index 4bb61d7a..a3c4f490 100644 --- a/docs/src/cdist-explorer.rst +++ b/docs/src/cdist-explorer.rst @@ -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. diff --git a/docs/src/cdist-features.rst b/docs/src/cdist-features.rst index 7018d248..be56fa22 100644 --- a/docs/src/cdist-features.rst +++ b/docs/src/cdist-features.rst @@ -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 diff --git a/docs/src/cdist-hacker.rst b/docs/src/cdist-hacker.rst index d7d6a056..ea5dceb3 100644 --- a/docs/src/cdist-hacker.rst +++ b/docs/src/cdist-hacker.rst @@ -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 diff --git a/docs/src/cdist-install.rst b/docs/src/cdist-install.rst index 38db1a4e..1e1e8245 100644 --- a/docs/src/cdist-install.rst +++ b/docs/src/cdist-install.rst @@ -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 diff --git a/docs/src/cdist-manifest.rst b/docs/src/cdist-manifest.rst index b29cf0d8..0e266943 100644 --- a/docs/src/cdist-manifest.rst +++ b/docs/src/cdist-manifest.rst @@ -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 `_ and of how types work in `cdist type `_. diff --git a/docs/src/cdist-stages.rst b/docs/src/cdist-stages.rst index fd19ce0d..751ba9c7 100644 --- a/docs/src/cdist-stages.rst +++ b/docs/src/cdist-stages.rst @@ -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. diff --git a/docs/src/cdist-why.rst b/docs/src/cdist-why.rst index e6aefefd..1123a1de 100644 --- a/docs/src/cdist-why.rst +++ b/docs/src/cdist-why.rst @@ -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 diff --git a/docs/src/man1/cdist.rst b/docs/src/man1/cdist.rst index ea3ded12..7112d14d 100644 --- a/docs/src/man1/cdist.rst +++ b/docs/src/man1/cdist.rst @@ -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