Restructure and fix and improve docs and manpages.
This commit is contained in:
Darko Poljak
parent
a220d4805a
commit
51c94e9e82
125 changed files with 1799 additions and 816 deletions
|
|
@ -2,6 +2,7 @@ Changelog
|
|||
---------
|
||||
|
||||
next:
|
||||
* Documentation: Restructure and fix and improve docs and manpages (Darko Poljak)
|
||||
* Core: Add files directory for static files (Darko Poljak)
|
||||
* Core: Fix conflicting requirements (Darko Poljak)
|
||||
* Custom: Add bash and zsh completions (Darko Poljak)
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ BUILDDIR = _build
|
|||
|
||||
# User-friendly check for sphinx-build
|
||||
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
|
||||
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don\'t have Sphinx installed, grab it from http://sphinx-doc.org/)
|
||||
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don\'t have Sphinx installed, grab it from http://sphinx-doc.org/)
|
||||
endif
|
||||
|
||||
# Internal variables.
|
||||
|
|
|
|||
|
|
@ -1,14 +1,8 @@
|
|||
cdist-best-practice(7)
|
||||
======================
|
||||
Best practice
|
||||
=============
|
||||
Practices used in real environments
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-best-practice - Practices used in real environments
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
PASSWORDLESS CONNECTIONS
|
||||
Passwordless connections
|
||||
------------------------
|
||||
It is recommended to run cdist with public key authentication.
|
||||
This requires a private/public key pair and the entry
|
||||
|
|
@ -16,7 +10,7 @@ This requires a private/public key pair and the entry
|
|||
See sshd_config(5) and ssh-keygen(1).
|
||||
|
||||
|
||||
SPEEDING UP SSH CONNECTIONS
|
||||
Speeding up ssh connections
|
||||
---------------------------
|
||||
When connecting to a new host, the initial delay with ssh connections
|
||||
is pretty big. You can work around this by
|
||||
|
|
@ -30,7 +24,7 @@ inclusion into your ~/.ssh/config::
|
|||
ControlPersist 10
|
||||
|
||||
|
||||
SPEEDING UP SHELL EXECUTION
|
||||
Speeding up shell execution
|
||||
----------------------------
|
||||
On the source host, ensure that /bin/sh is *not* bash: bash is quite slow for
|
||||
script execution. Instead, you could use dash after installing it::
|
||||
|
|
@ -38,7 +32,7 @@ script execution. Instead, you could use dash after installing it::
|
|||
ln -sf /bin/dash /bin/sh
|
||||
|
||||
|
||||
MULTI MASTER OR ENVIRONMENT SETUPS
|
||||
Multi master or environment setups
|
||||
----------------------------------
|
||||
If you plan to distribute cdist among servers or use different
|
||||
environments, you can do so easily with the included version
|
||||
|
|
@ -64,7 +58,7 @@ you can clone it multiple times::
|
|||
machine-b % git clone git://your-git-server/cdist
|
||||
|
||||
|
||||
SEPERATING WORK BY GROUPS
|
||||
Seperating work by groups
|
||||
-------------------------
|
||||
If you are working with different groups on one cdist-configuration,
|
||||
you can delegate to other manifests and have the groups edit only
|
||||
|
|
@ -77,7 +71,7 @@ their manifests. You can use the following snippet in
|
|||
sh -e "$__manifest/cbrg"
|
||||
|
||||
|
||||
MAINTAINING MULTIPLE CONFIGURATIONS
|
||||
Maintaining multiple configurations
|
||||
-----------------------------------
|
||||
When you need to manage multiple sites with cdist, like company_a, company_b
|
||||
and private for instance, you can easily use git for this purpose.
|
||||
|
|
@ -138,7 +132,7 @@ The following **.git/config** is taken from a a real world scenario::
|
|||
Have a look at git-remote(1) to adjust the remote configuration, which allows
|
||||
|
||||
|
||||
MULTIPLE DEVELOPERS WITH DIFFERENT TRUST
|
||||
Multiple developers with different trust
|
||||
----------------------------------------
|
||||
If you are working in an environment that requires different people to
|
||||
work on the same configuration, but having different privileges, you can
|
||||
|
|
@ -155,7 +149,7 @@ implement this scenario with a gateway host and sudo:
|
|||
For more details consult sudoers(5)
|
||||
|
||||
|
||||
TEMPLATING
|
||||
Templating
|
||||
----------
|
||||
* create directory files/ in your type (convention)
|
||||
* create the template as an executable file like files/basic.conf.sh, it will output text using shell variables for the values
|
||||
|
|
@ -193,7 +187,7 @@ TEMPLATING
|
|||
--source "$__object/files/basic.conf"
|
||||
|
||||
|
||||
TESTING A NEW TYPE
|
||||
Testing a new type
|
||||
------------------
|
||||
If you want to test a new type on a node, you can tell cdist to only use an
|
||||
object of this type: Use the '--initial-manifest' parameter
|
||||
|
|
@ -214,7 +208,7 @@ of cdist:
|
|||
cdist --initial-manifest - cdist-dev-01.ungleich.ch
|
||||
|
||||
|
||||
OTHER CONTENT IN CDIST REPOSITORY
|
||||
Other content in cdist repository
|
||||
---------------------------------
|
||||
Usually the cdist repository contains all configuration
|
||||
items. Sometimes you may have additional resources that
|
||||
|
|
@ -227,15 +221,3 @@ in the repository for such content: It allows you to
|
|||
easily distinguish what is used by cdist and what not
|
||||
and also to store all important files in one
|
||||
repository.
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist(1) <../man1/cdist.html>`_
|
||||
- `cdist-tutorial(7) <cdist-tutorial.html>`_
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
Copyright \(C) 2011-2013 Nico Schottelius. Free use of this software is
|
||||
granted under the terms of the GNU General Public License version 3 (GPLv3).
|
||||
|
|
@ -1,21 +1,11 @@
|
|||
cdist-bootstrap(7)
|
||||
==================
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-bootstrap - Setup cdist environment
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
INTRODUCTION
|
||||
------------
|
||||
Bootstrap
|
||||
=========
|
||||
This document describes the usual steps recommended for a new
|
||||
cdist setup. It is recommended that you have read and understood
|
||||
cdist-quickstart(7) before digging into this.
|
||||
`cdist quickstart <cdist-quickstart.html>`_ before digging into this.
|
||||
|
||||
|
||||
LOCATION
|
||||
Location
|
||||
---------
|
||||
First of all, you should think about where to store your configuration
|
||||
database and who will be accessing or changing it. Secondly you have to
|
||||
|
|
@ -29,13 +19,13 @@ relies on is recommended, for use as backup as well as to allow easy collaborati
|
|||
with others.
|
||||
|
||||
For more sophisticated setups developing cdist configurations with multiple
|
||||
people, have a look at cdist-best-practice(7).
|
||||
people, have a look at `cdist best practice <cdist-best-practice.html>`_.
|
||||
|
||||
|
||||
SETUP WORKING DIRECTORY AND BRANCH
|
||||
Setup working directory and branch
|
||||
----------------------------------
|
||||
I assume you have a fresh copy of the cdist tree in ~/cdist, cloned from
|
||||
one of the official urls (see cdist-quickstart(7) if you don't).
|
||||
one of the official urls (see `cdist quickstart <cdist-quickstart.html>`_ if you don't).
|
||||
Entering the command "git branch" should show you "* master", which indicates
|
||||
you are on the **master** branch.
|
||||
|
||||
|
|
@ -85,7 +75,7 @@ In this tutorial I use the branch **mycompany**::
|
|||
From now on, you can use git as usual to commit your changes in your own branch.
|
||||
|
||||
|
||||
PUBLISHING THE CONFIGURATION
|
||||
Publishing the configuration
|
||||
----------------------------
|
||||
Usually a development machine like a notebook should be considered
|
||||
temporary only. For this reason and to enable shareability, the configuration
|
||||
|
|
@ -114,7 +104,7 @@ branch with the **master** branch on the host **loch**. Thus you can commit
|
|||
as usual in your branch and push out changes by entering **git push**.
|
||||
|
||||
|
||||
UPDATING FROM ORIGIN
|
||||
Updating from origin
|
||||
--------------------
|
||||
Whenever you want to update your cdist installation, you can use git to do so::
|
||||
|
||||
|
|
@ -126,15 +116,3 @@ Whenever you want to update your cdist installation, you can use git to do so::
|
|||
|
||||
# Alternative: Update current branch with 2.0 branch from origin
|
||||
cdist% git merge origin/2.0
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist(1) <../man1/cdist.html>`_
|
||||
- `cdist-tutorial(7) <cdist-tutorial.html>`_
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
Copyright \(C) 2012 Nico Schottelius. Free use of this software is
|
||||
granted under the terms of the GNU General Public License version 3 (GPLv3).
|
||||
|
|
@ -1,14 +1,7 @@
|
|||
cdist-explorer(7)
|
||||
=================
|
||||
Explorer
|
||||
========
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-explorer - Explore the target systems
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
DESCRIPTION
|
||||
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
|
||||
|
|
@ -39,7 +32,7 @@ error message on stderr, which will cause cdist to abort.
|
|||
You can also use stderr for debugging purposes while developing a new
|
||||
explorer.
|
||||
|
||||
EXAMPLES
|
||||
Examples
|
||||
--------
|
||||
A very simple explorer may look like this::
|
||||
|
||||
|
|
@ -59,16 +52,3 @@ A type explorer, which could check for the status of a package may look like thi
|
|||
|
||||
# Expect dpkg failing, if package is not known / installed
|
||||
dpkg -s "$name" 2>/dev/null || exit 0
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist(1) <../man1/cdist.html>`_
|
||||
- `cdist-reference(7) <cdist-reference.html>`_
|
||||
- `cdist-stages(7) <cdist-stages.html>`_
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
Copyright \(C) 2010-2014 Nico Schottelius. Free use of this software is
|
||||
granted under the terms of the GNU General Public License version 3 (GPLv3).
|
||||
48
docs/man/cdist-features.rst
Normal file
48
docs/man/cdist-features.rst
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
Features
|
||||
========
|
||||
|
||||
But cdist ticks differently, here is the feature set that makes it unique:
|
||||
|
||||
Simplicity
|
||||
There is only one type to extend cdist called **type**
|
||||
|
||||
Design
|
||||
+ Type and core cleanly seperated
|
||||
+ Sticks completly to the KISS (keep it simple and stupid) paradigma
|
||||
+ 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
|
||||
+ Define target state, do not focus on methods or scripts
|
||||
+ Push architecture: Instantly apply your changes
|
||||
|
||||
Small core
|
||||
cdist's core is very small - less code, less bugs
|
||||
|
||||
Fast development
|
||||
Focus on straightforwardness of type creation is a main development objective
|
||||
Batteries included: A lot of requirements can be solved using standard types
|
||||
|
||||
Modern Programming Language
|
||||
cdist is written in Python
|
||||
|
||||
Requirements, Scalability
|
||||
No central server needed, cdist operates in push mode and can be run from any computer
|
||||
|
||||
Requirements, Scalability, Upgrade
|
||||
cdist only needs to be updated on the master, not on the target hosts
|
||||
|
||||
Requirements, Security
|
||||
Uses well-know `SSH <http://www.openssh.com/>`_ as transport protocol
|
||||
|
||||
Requirements, Simplicity
|
||||
Requires only shell and SSH server on the target
|
||||
|
||||
UNIX
|
||||
Reuse of existing tools like cat, find, mv, ...
|
||||
|
||||
UNIX, familar environment, documentation
|
||||
Is available as manpages and HTML
|
||||
|
||||
UNIX, simplicity, familar environment
|
||||
cdist is configured in POSIX shell
|
||||
|
||||
|
|
@ -1,14 +1,7 @@
|
|||
cdist-hacker(7)
|
||||
===============
|
||||
Hacking
|
||||
=======
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-hacker - How to get (stuff) into cdist
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
WELCOME
|
||||
Welcome
|
||||
-------
|
||||
Welcome dear hacker! I invite you to a tour of pointers to
|
||||
get into the usable configuration mangament system, cdist.
|
||||
|
|
@ -19,14 +12,14 @@ twice before merging or implementing a feature: Less features
|
|||
with good usability are far better than the opposite.
|
||||
|
||||
|
||||
REPORTING BUGS
|
||||
Reporting bugs
|
||||
--------------
|
||||
If you believe you've found a bug and verified that it is
|
||||
in the latest version, drop a mail to the cdist mailing list,
|
||||
subject prefixed with "[BUG] " or create an issue on github.
|
||||
|
||||
|
||||
CODING CONVENTIONS (EVERYWHERE)
|
||||
Coding conventions (everywhere)
|
||||
-------------------------------
|
||||
If something should be better done or needs to fixed, add the word FIXME
|
||||
nearby, so grepping for FIXME gives all positions that need to be fixed.
|
||||
|
|
@ -34,7 +27,7 @@ nearby, so grepping for FIXME gives all positions that need to be fixed.
|
|||
Indention is 4 spaces (welcome to the python world).
|
||||
|
||||
|
||||
HOW TO SUBMIT STUFF FOR INCLUSION INTO UPSTREAM CDIST
|
||||
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.
|
||||
|
|
@ -61,9 +54,9 @@ for inclusion to the mailinglist **cdist at cdist -- at -- l.schottelius.org**
|
|||
or open a pull request at http://github.com/telmich/cdist.
|
||||
|
||||
|
||||
HOW TO SUBMIT A NEW TYPE
|
||||
How to submit a new type
|
||||
------------------------
|
||||
For detailled information about types, see cdist-type(7).
|
||||
For detailled information about types, see `cdist type <cdist-type.html>`_.
|
||||
|
||||
Submitting a type works as described above, with the additional requirement
|
||||
that a corresponding manpage named man.text in asciidoc format with
|
||||
|
|
@ -77,9 +70,11 @@ code and thus such a type introduces redundant functionality that is given by
|
|||
core cdist already.
|
||||
|
||||
|
||||
EXAMPLE GIT WORKFLOW
|
||||
Example git workflow
|
||||
---------------------
|
||||
The following workflow works fine for most developers::
|
||||
The following workflow works fine for most developers
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
# get latest upstream master branch
|
||||
git clone https://github.com/telmich/cdist.git
|
||||
|
|
@ -125,6 +120,8 @@ The following workflow works fine for most developers::
|
|||
If at any point you want to go back to the original master branch, you can
|
||||
use **git stash** to stash your changes away::
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
# assume you are on documentation_cleanup
|
||||
git stash
|
||||
|
||||
|
|
@ -136,6 +133,8 @@ use **git stash** to stash your changes away::
|
|||
Similar 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
|
||||
|
||||
# change to master and update to most recent upstream version
|
||||
git checkout master
|
||||
git fetch -v origin
|
||||
|
|
@ -145,17 +144,3 @@ to the master branch and create another branch based on it::
|
|||
|
||||
(you can repeat the code above for as many features as you want to develop
|
||||
in parallel)
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist(1) <../man1/cdist.html>`_
|
||||
- git(1)
|
||||
- git-checkout(1)
|
||||
- git-stash(1)
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
Copyright \(C) 2011-2013 Nico Schottelius. Free use of this software is
|
||||
granted under the terms of the GNU General Public License version 3 (GPLv3).
|
||||
105
docs/man/cdist-install.rst
Normal file
105
docs/man/cdist-install.rst
Normal file
|
|
@ -0,0 +1,105 @@
|
|||
How to install cdist
|
||||
====================
|
||||
|
||||
Requirements
|
||||
-------------
|
||||
|
||||
Source Host
|
||||
~~~~~~~~~~~
|
||||
|
||||
This is the machine you use to configure the target hosts.
|
||||
|
||||
* /bin/sh: A posix like shell (for instance bash, dash, zsh)
|
||||
* Python >= 3.2
|
||||
* SSH client
|
||||
* sphinx (for building html docs and/or the manpages)
|
||||
|
||||
Target Hosts
|
||||
~~~~~~~~~~~~
|
||||
|
||||
* /bin/sh: A posix like shell (for instance bash, dash, zsh)
|
||||
* SSH server
|
||||
|
||||
Install cdist
|
||||
-------------
|
||||
|
||||
You can install cdist either from git or as a python package.
|
||||
|
||||
From git
|
||||
~~~~~~~~
|
||||
|
||||
Cloning cdist from git gives you the advantage of having
|
||||
a version control in place for development of your own stuff
|
||||
immediately.
|
||||
|
||||
To install cdist, execute the following commands:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
git clone https://github.com/ungleich/cdist.git
|
||||
cd cdist
|
||||
export PATH=$PATH:$(pwd -P)/bin
|
||||
|
||||
Available versions in git
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* The active development takes place in the **master** branch
|
||||
* The released versions can be found in the tags
|
||||
|
||||
Other branches may be available for features or bugfixes, but they
|
||||
may vanish at any point. To select a specific branch use
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
# Generic code
|
||||
git checkout -b <localbranchname> origin/<branchname>
|
||||
|
||||
So for instance if you want to use and stay with version 4.1, you can use
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
git checkout -b 4.1 origin/4.1
|
||||
|
||||
Git mirrors
|
||||
^^^^^^^^^^^
|
||||
|
||||
If the main site is down, you can acquire cdist from one of the following sites:
|
||||
|
||||
* git://github.com/telmich/cdist.git `github <https://github.com/telmich/cdist>`_
|
||||
* git://git.code.sf.net/p/cdist/code `sourceforge <https://sourceforge.net/p/cdist/code>`_
|
||||
|
||||
Building and using manpages
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If you want to build and use the manpages, run:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
make man
|
||||
export MANPATH=$MANPATH:$(pwd -P)/docs/man/_build/man
|
||||
|
||||
Or you can move manpages from docs/man/_build/man directory to some
|
||||
other directory and add it to MANPATH.
|
||||
|
||||
You can also build manpages for types in your ~/.cdist directory:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
make dotman
|
||||
|
||||
Built manpages are now in docs/man/_build/man directory. If you have
|
||||
some other custom .cdist directory, e.g. /custom/.cdist then use:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
DOT_CDIST_PATH=/custom/.cdist make dotman
|
||||
|
||||
Python package
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
Cdist is available as a python package at
|
||||
`PyPi <http://pypi.python.org/pypi/cdist/>`_. You can install it using
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
pip install cdist
|
||||
15
docs/man/cdist-intro.rst
Normal file
15
docs/man/cdist-intro.rst
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
cdist - usable configuration management
|
||||
=======================================
|
||||
|
||||
.. image:: cdist-logo.png
|
||||
:alt: cdist-logo
|
||||
|
||||
cdist is a usable configuration management system.
|
||||
It adheres to the KISS principle and
|
||||
is being used in small up to enterprise grade environments.
|
||||
cdist is an alternative to other configuration management systems like
|
||||
|
||||
* `bcfg2 <http://trac.mcs.anl.gov/projects/bcfg2>`_
|
||||
* `chef <http://wiki.opscode.com/display/chef/>`_
|
||||
* `cfengine <http://www.cfengine.org/>`_
|
||||
* `puppet <http://www.puppetlabs.com/>`_.
|
||||
BIN
docs/man/cdist-logo.png
Normal file
BIN
docs/man/cdist-logo.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.5 KiB |
|
|
@ -1,14 +1,7 @@
|
|||
cdist-manifest(7)
|
||||
=================
|
||||
Manifest
|
||||
========
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-manifest - (Re-)Use types
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
DESCRIPTION
|
||||
Description
|
||||
-----------
|
||||
Manifests are used to define which objects to create.
|
||||
Objects are instances of **types**, like in object oriented programming languages.
|
||||
|
|
@ -44,15 +37,15 @@ In general, manifests are used to define which types are used depending
|
|||
on given conditions.
|
||||
|
||||
|
||||
INITIAL AND TYPE MANIFESTS
|
||||
Initial and type manifests
|
||||
--------------------------
|
||||
Cdist knows about two types of manifests: The initial manifest and type
|
||||
manifests. The initial manifest is used to define, which configurations
|
||||
to apply to which hosts. The type manifests are used to create objects
|
||||
from types. More about manifests in types can be found in cdist-type(7).
|
||||
from types. More about manifests in types can be found in `cdist type <cdist-type.html>`_.
|
||||
|
||||
|
||||
DEFINE STATE IN THE INITIAL MANIFEST
|
||||
Define state in the initial manifest
|
||||
------------------------------------
|
||||
The **initial manifest** is the entry point for cdist to find out, which
|
||||
**objects** to configure on the selected host.
|
||||
|
|
@ -82,12 +75,12 @@ utilises cdist types. Every available type can be executed like a normal
|
|||
command.
|
||||
|
||||
|
||||
SPLITTING UP THE INITIAL MANIFEST
|
||||
Splitting up the initial manifest
|
||||
---------------------------------
|
||||
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**.
|
||||
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 <cdist-reference.html>`_).
|
||||
|
||||
The following example would include every file with a **.sh** suffix::
|
||||
|
||||
|
|
@ -98,7 +91,7 @@ The following example would include every file with a **.sh** suffix::
|
|||
done
|
||||
|
||||
|
||||
DEPENDENCIES
|
||||
Dependencies
|
||||
------------
|
||||
If you want to describe that something requires something else, just
|
||||
setup the variable "require" to contain the requirements. Multiple
|
||||
|
|
@ -157,10 +150,10 @@ 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
|
||||
in cdist-stages(7) and of how types work in cdist-type(7).
|
||||
in `cdist execution stages <cdist-stages.html>`_ and of how types work in `cdist type <cdist-type.html>`_.
|
||||
|
||||
|
||||
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
|
||||
in the manifest by setting up the variable CDIST_ORDER_DEPENDENCY.
|
||||
|
|
@ -171,7 +164,7 @@ It essentially helps you to build up blocks of code that build upon each other
|
|||
(like first creating the directory xyz than the file below the directory).
|
||||
|
||||
|
||||
OVERRIDES
|
||||
Overrides
|
||||
---------
|
||||
In some special cases, you would like to create an already defined object
|
||||
with different parameters. In normal situations this leads to an error in cdist.
|
||||
|
|
@ -187,7 +180,7 @@ CDIST_ORDER_DEPENDENCY will be ignored, because adding a dependency in case of
|
|||
overrides would result in circular dependencies, which is an error.
|
||||
|
||||
|
||||
EXAMPLES
|
||||
Examples
|
||||
--------
|
||||
The initial manifest may for instance contain the following code:
|
||||
|
||||
|
|
@ -260,15 +253,3 @@ Dependencies defined by execution order work as following:
|
|||
require="__some_type_somewhere/id __sample_type/1" __sample_type 2
|
||||
require="__sample_type/2" __example_type 23
|
||||
__not_in_order_type 42
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist-tutorial(7) <cdist-tutorial.html>`_
|
||||
- `cdist-type(7) <cdist-type.html>`_
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
Copyright \(C) 2010-2014 Nico Schottelius. Free use of this software is
|
||||
granted under the terms of the GNU General Public License version 3 (GPLv3).
|
||||
|
|
@ -1,13 +1,7 @@
|
|||
cdist-messaging(7)
|
||||
==================
|
||||
Messaging
|
||||
=========
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-messaging - How the initial manifest and types can communication
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
DESCRIPTION
|
||||
Description
|
||||
-----------
|
||||
cdist has a simple but powerful way of allowing communication between
|
||||
the initial manifest and types as well as types and types.
|
||||
|
|
@ -27,11 +21,11 @@ This way overwriting any of the two files by accident does not
|
|||
interfere with other types.
|
||||
|
||||
The order of execution is not defined unless you create dependencies
|
||||
between the different objects (see cdist-manifest(7)) and thus you
|
||||
between the different objects (see `cdist manifest <cdist-manifest.html>`_) and thus you
|
||||
can only react reliably on messages by objects that you depend on.
|
||||
|
||||
|
||||
AVAILABILITY
|
||||
Availability
|
||||
------------
|
||||
Messaging is possible between all **local** scripts:
|
||||
|
||||
|
|
@ -41,7 +35,7 @@ Messaging is possible between all **local** scripts:
|
|||
- type/gencode-remote
|
||||
|
||||
|
||||
EXAMPLES
|
||||
Examples
|
||||
--------
|
||||
When you want to emit a message use:
|
||||
|
||||
|
|
@ -98,17 +92,3 @@ Restart sshd on changes
|
|||
if grep -q "^__key_value/PermitRootLogin" "$__messages_in"; then
|
||||
echo $restart
|
||||
fi
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist(1) <../man1/cdist.html>`_
|
||||
- `cdist-manifest(7) <cdist-manifest.html>`_
|
||||
- `cdist-reference(7) <cdist-reference.html>`_
|
||||
- `cdist-type(7) <cdist-type.html>`_
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
Copyright \(C) 2013 Nico Schottelius. Free use of this software is
|
||||
granted under the terms of the GNU General Public License version 3 (GPLv3).
|
||||
16
docs/man/cdist-os.rst
Normal file
16
docs/man/cdist-os.rst
Normal file
|
|
@ -0,0 +1,16 @@
|
|||
Supported Operating Systems
|
||||
===========================
|
||||
|
||||
cdist was tested or is know to run on at least
|
||||
|
||||
* `Archlinux <http://www.archlinux.org/>`_
|
||||
* `Debian <http://www.debian.org/>`_
|
||||
* `CentOS <http://www.centos.org/>`_
|
||||
* `Fedora <http://fedoraproject.org/>`_
|
||||
* `FreeBSD <http://www.freebsd.org>`_
|
||||
* `Gentoo <http://www.gentoo.org/>`_
|
||||
* `Mac OS X <http://www.apple.com/macosx/>`_
|
||||
* `OpenBSD <http://www.openbsd.org>`_
|
||||
* `Redhat <http://www.redhat.com/>`_
|
||||
* `Ubuntu <http://www.ubuntu.com/>`_
|
||||
* `XenServer <http://www.citrix.com/xenserver/>`_
|
||||
|
|
@ -1,31 +1,18 @@
|
|||
cdist-quickstart(7)
|
||||
===================
|
||||
Quickstart
|
||||
==========
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-quickstart - Jump in and enjoy cdist
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
INTRODUCTION
|
||||
------------
|
||||
This tutorial is aimed at people learning cdist and shows
|
||||
typical approaches as well as gives an easy start into
|
||||
the world of configuration management.
|
||||
|
||||
This tutorial assumes you are configuring **localhost**, because
|
||||
it is always available. Just replace **localhost** with your target
|
||||
host for real life usage.
|
||||
|
||||
|
||||
|
||||
QUICK START - GET YOUR HANDS DIRTY NOW
|
||||
--------------------------------------
|
||||
For those who just want to configure a system with the
|
||||
cdist configuration management and do not need (or want)
|
||||
to understand everything.
|
||||
|
||||
This tutorial assumes you are configuring **localhost**, because
|
||||
it is always available. Just replace **localhost** with your target
|
||||
host for real life usage.
|
||||
|
||||
Cdist uses **ssh** for communication and transportation
|
||||
and usually logs into the **target host** as the
|
||||
**root** user. So you need to configure the **ssh server**
|
||||
|
|
@ -84,15 +71,3 @@ code into your shell to get started and configure localhost::
|
|||
That's it, you've successfully used cdist to configure your first host!
|
||||
Continue reading the next sections, to understand what you did and how
|
||||
to create a more sophisticated configuration.
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist(1) <../man1/cdist.html>`_
|
||||
- `cdist-tutorial(7) <cdist-tutorial.html>`_
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
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).
|
||||
|
|
@ -29,23 +29,17 @@ __cdist_myname=${0##*/};
|
|||
__cdist_abs_myname="$__cdist_abs_mydir/$__cdist_myname"
|
||||
|
||||
filename="${__cdist_myname%.sh}"
|
||||
dest="$__cdist_abs_mydir/man7/$filename"
|
||||
dest="$__cdist_abs_mydir/$filename"
|
||||
|
||||
cd "$__cdist_abs_mydir"
|
||||
|
||||
exec > "$dest"
|
||||
cat << eof
|
||||
cdist-reference(7)
|
||||
==================
|
||||
Reference
|
||||
=========
|
||||
Variable, path and type reference for cdist
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-reference - Variable, path and type reference for cdist
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
EXPLORERS
|
||||
Explorers
|
||||
---------
|
||||
The following global explorers are available:
|
||||
|
||||
|
|
@ -59,7 +53,7 @@ eof
|
|||
|
||||
cat << eof
|
||||
|
||||
PATHS
|
||||
Paths
|
||||
-----
|
||||
\$HOME/.cdist
|
||||
The standard cdist configuration directory relative to your home directory
|
||||
|
|
@ -76,10 +70,6 @@ confdir
|
|||
By default it consists of everything in \$HOME/.cdist and cdist/conf/.
|
||||
For more details see cdist(1)
|
||||
|
||||
confdir/files/
|
||||
Cdist does not care about this directory besides providing access to it.
|
||||
It is thought to be a general file storage area.
|
||||
|
||||
confdir/manifest/init
|
||||
This is the central entry point.
|
||||
It is an executable (+x bit set) shell script that can use
|
||||
|
|
@ -94,11 +84,11 @@ confdir/manifest/*
|
|||
maintain different groups of hosts.
|
||||
|
||||
confdir/explorer/<name>
|
||||
Contains explorers to be run on the target hosts, see cdist-explorer(7).
|
||||
Contains explorers to be run on the target hosts, see \`cdist explorer <cdist-explorer.html>\`_.
|
||||
|
||||
confdir/type/
|
||||
Contains all available types, which are used to provide
|
||||
some kind of functionality. See cdist-type(7).
|
||||
some kind of functionality. See \`cdist type <cdist-type.html>\`_.
|
||||
|
||||
confdir/type/<name>/
|
||||
Home of the type <name>.
|
||||
|
|
@ -133,7 +123,7 @@ confdir/type/<name>/parameter/boolean
|
|||
confdir/type/<name>/explorer
|
||||
Location of the type specific explorers.
|
||||
This directory is referenced by the variable __type_explorer (see below).
|
||||
See cdist-explorer(7).
|
||||
See \`cdist explorer <cdist-explorer.html>\`_.
|
||||
|
||||
confdir/type/<name>/files
|
||||
This directory is reserved for user data and will not be used
|
||||
|
|
@ -158,27 +148,28 @@ out/object/<object>
|
|||
out/object/<object>/explorers
|
||||
Output of type specific explorers, per object.
|
||||
|
||||
TYPES
|
||||
Types
|
||||
-----
|
||||
The following types are available:
|
||||
|
||||
eof
|
||||
|
||||
for type in $(ls man7/cdist-type__*.rst | LC_ALL=C sort); do
|
||||
# If there is no such file then ls prints error to stderr,
|
||||
# so redirect stderr to /dev/null.
|
||||
for type in $(ls man7/cdist-type__*.rst 2>/dev/null | LC_ALL=C sort); do
|
||||
no_dir="${type#man7/}";
|
||||
no_type="${no_dir#cdist-type}";
|
||||
name="${no_type%.rst}";
|
||||
name_no_underline="$(echo $name | sed 's/^__/\\__/g')"
|
||||
manref="${no_dir%.rst}"
|
||||
man="${manref}(7)"
|
||||
|
||||
echo "- $name_no_underline" "(\`${man} <${manref}.html>\`_)"
|
||||
echo "- $name" "(\`${man} <man7/${manref}.html>\`_)"
|
||||
done
|
||||
|
||||
cat << eof
|
||||
|
||||
|
||||
OBJECTS
|
||||
Objects
|
||||
-------
|
||||
For object to object communication and tests, the following paths are
|
||||
usable within a object directory:
|
||||
|
|
@ -195,17 +186,13 @@ stdin
|
|||
when the type was called.
|
||||
|
||||
|
||||
ENVIRONMENT VARIABLES (FOR READING)
|
||||
Environment variables (for reading)
|
||||
-----------------------------------
|
||||
The following environment variables are exported by cdist:
|
||||
|
||||
__explorer
|
||||
Directory that contains all global explorers.
|
||||
Available for: initial manifest, explorer, type explorer, shell
|
||||
__files
|
||||
Directory that contains content from the "files" subdirectories
|
||||
from the configuration directories.
|
||||
Available for: initial manifest, type manifest, type gencode, shell
|
||||
__manifest
|
||||
Directory that contains the initial manifest.
|
||||
Available for: initial manifest, type manifest, shell
|
||||
|
|
@ -240,12 +227,12 @@ __type_explorer
|
|||
Directory that contains the type explorers.
|
||||
Available for: type explorer
|
||||
|
||||
ENVIRONMENT VARIABLES (FOR WRITING)
|
||||
Environment variables (for writing)
|
||||
-----------------------------------
|
||||
The following environment variables influence the behaviour of cdist:
|
||||
|
||||
require
|
||||
Setup dependencies between objects (see cdist-manifest(7))
|
||||
Setup dependencies between objects (see \`cdist manifest <cdist-manifest.html>\`_)
|
||||
|
||||
CDIST_LOCAL_SHELL
|
||||
Use this shell locally instead of /bin/sh to execute scripts
|
||||
|
|
@ -254,24 +241,14 @@ CDIST_REMOTE_SHELL
|
|||
Use this shell remotely instead of /bin/sh to execute scripts
|
||||
|
||||
CDIST_OVERRIDE
|
||||
Allow overwriting type parameters (see cdist-manifest(7))
|
||||
Allow overwriting type parameters (see \`cdist manifest <cdist-manifest.html>\`_)
|
||||
|
||||
CDIST_ORDER_DEPENDENCY
|
||||
Create dependencies based on the execution order (see cdist-manifest(7))
|
||||
Create dependencies based on the execution order (see \`cdist manifest <cdist-manifest.html>\`_)
|
||||
|
||||
CDIST_REMOTE_EXEC
|
||||
Use this command for remote execution (should behave like ssh)
|
||||
|
||||
CDIST_REMOTE_COPY
|
||||
Use this command for remote copy (should behave like scp)
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- \`cdist(1) <../man1/cdist.html>\`_
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
Copyright \(C) 2011-2014 Nico Schottelius. Free use of this software is
|
||||
granted under the terms of the GNU General Public License version 3 (GPLv3).
|
||||
eof
|
||||
|
|
|
|||
|
|
@ -1,15 +1,6 @@
|
|||
cdist-remote-exec-copy(7)
|
||||
=========================
|
||||
Remote exec and copy commands
|
||||
=============================
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-remote-exec-copy - How to use remote exec and copy
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
INTRO
|
||||
-----
|
||||
Cdist interacts with the target host in two ways:
|
||||
|
||||
- it executes code (__remote_exec)
|
||||
|
|
@ -30,19 +21,3 @@ For __remote_copy, it must behave like scp.
|
|||
With this simple interface the user can take total control of how cdist
|
||||
interacts with the target when required, while the default implementation
|
||||
remains as simple as possible.
|
||||
|
||||
|
||||
EXAMPLES
|
||||
--------
|
||||
See cdist/other/examples/remote/ for some example implementations.
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist(1) <../man1/cdist.html>`_
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
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).
|
||||
|
|
@ -1,19 +1,13 @@
|
|||
cdist-stages(7)
|
||||
===============
|
||||
Execution stages
|
||||
================
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-stages - Stages used during configuration deployment
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
DESCRIPTION
|
||||
Description
|
||||
-----------
|
||||
Starting the execution of deployment with cdist, cdist passes
|
||||
through different stages.
|
||||
|
||||
|
||||
STAGE 1: TARGET INFORMATION RETRIEVAL
|
||||
Stage 1: target information retrieval
|
||||
-------------------------------------
|
||||
In this stage information is collected about the target host using so called
|
||||
explorers. Every existing explorer is run on the target and the output of all
|
||||
|
|
@ -21,7 +15,7 @@ explorers are copied back into the local cache. The results can be used by
|
|||
manifests and types.
|
||||
|
||||
|
||||
STAGE 2: RUN THE INITIAL MANIFEST
|
||||
Stage 2: run the initial manifest
|
||||
---------------------------------
|
||||
The initial manifest, which should be used for mappings of hosts to types,
|
||||
is executed. This stage creates objects in a cconfig database that contains
|
||||
|
|
@ -30,7 +24,7 @@ no conflicts may occur, i.e. no object of the same type with the same id may
|
|||
be created, if it has different parameters.
|
||||
|
||||
|
||||
STAGE 3: OBJECT INFORMATION RETRIEVAL
|
||||
Stage 3: object information retrieval
|
||||
-------------------------------------
|
||||
Every object is checked whether its type has explorers and if so, these are
|
||||
executed on the target host. The results are transferred back
|
||||
|
|
@ -38,7 +32,7 @@ and can be used in the following stages to decide what changes need to be made
|
|||
on the target to implement the desired state.
|
||||
|
||||
|
||||
STAGE 4: RUN THE OBJECT MANIFEST
|
||||
Stage 4: run the object manifest
|
||||
--------------------------------
|
||||
Every object is checked whether its type has a executable manifest. The
|
||||
manifest script may generate and change the created objects. In other words,
|
||||
|
|
@ -52,7 +46,7 @@ may occur during the merge. A conflict would mean that two different objects
|
|||
try to create the same object, which indicates a broken configuration.
|
||||
|
||||
|
||||
STAGE 5: CODE GENERATION
|
||||
Stage 5: code generation
|
||||
------------------------
|
||||
In this stage for every created object its type is checked for executable
|
||||
gencode scripts. The gencode scripts generate the code to be executed on the
|
||||
|
|
@ -60,30 +54,18 @@ target on stdout. If the gencode executables fail, they must print diagnostic
|
|||
messages on stderr and exit non-zero.
|
||||
|
||||
|
||||
STAGE 6: CODE EXECUTION
|
||||
Stage 6: code execution
|
||||
-----------------------
|
||||
For every object the resulting code from the previous stage is transferred to
|
||||
the target host and executed there to apply the configuration changes.
|
||||
|
||||
|
||||
STAGE 7: CACHE
|
||||
Stage 7: cache
|
||||
--------------
|
||||
The cache stores the information from the current run for later use.
|
||||
|
||||
|
||||
SUMMARY
|
||||
Summary
|
||||
-------
|
||||
If, and only if, all the stages complete without an errors, the configuration
|
||||
will be applied to the target.
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist(1) <../man1/cdist.html>`_
|
||||
- `cdist-reference(7) <cdist-reference.html>`_
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
Copyright \(C) 2010-2012 Nico Schottelius, Steven Armstrong. Free use of this software is
|
||||
granted under the terms of the GNU General Public License version 3 (GPLv3).
|
||||
28
docs/man/cdist-support.rst
Normal file
28
docs/man/cdist-support.rst
Normal file
|
|
@ -0,0 +1,28 @@
|
|||
Support
|
||||
-------
|
||||
|
||||
IRC
|
||||
~~~
|
||||
|
||||
You can join the development ***IRC channel***
|
||||
`#cstar on irc.freenode.net <irc://irc.freenode.org/#cstar>`_.
|
||||
|
||||
Mailing list
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Bug reports, questions, patches, etc. should be send to the
|
||||
`cdist mailing list <https://groups.google.com/forum/#!forum/cdist-configuration-management>`_.
|
||||
|
||||
Linkedin
|
||||
~~~~~~~~
|
||||
|
||||
If you have an account
|
||||
at `Linked in <http://www.linkedin.com/>`_,
|
||||
you can join the
|
||||
`cdist group <http://www.linkedin.com/groups/cdist-configuration-management-3952797>`_.
|
||||
|
||||
Commercial support
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You can request commercial support for cdist from
|
||||
`my company <http://www.ungleich.ch/>`_.
|
||||
|
|
@ -1,14 +1,7 @@
|
|||
cdist-troubleshooting(7)
|
||||
========================
|
||||
Troubleshooting
|
||||
===============
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-troubleshooting - Common problems and their solutions
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
ERROR IN MANIFEST IS NOT CONSIDERED AN ERROR BY CDIST
|
||||
Error in manifest is not considered an error by cdist
|
||||
-----------------------------------------------------
|
||||
Situation: You are executing other scripts from a manifest.
|
||||
This script fails, but cdist does not recognise the error.
|
||||
|
|
@ -50,15 +43,3 @@ you write to use the -e flag:
|
|||
% cat ~/.cdist/manifest/special
|
||||
#!/bin/sh -e
|
||||
...
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist(1) <../man1/cdist.html>`_
|
||||
- `cdist-tutorial(7) <cdist-tutorial.html>`_
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
Copyright \(C) 2013 Nico Schottelius. Free use of this software is
|
||||
granted under the terms of the GNU General Public License version 3 (GPLv3).
|
||||
|
|
@ -1,31 +1,24 @@
|
|||
cdist-type(7)
|
||||
=============
|
||||
cdist type
|
||||
==========
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-type - Functionality bundled
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
|
||||
::
|
||||
|
||||
__TYPE ID --parameter value [--parameter value ...]
|
||||
__TYPE --parameter value [--parameter value ...] (for singletons)
|
||||
|
||||
|
||||
DESCRIPTION
|
||||
Description
|
||||
-----------
|
||||
Types are the main component of cdist and define functionality. If you
|
||||
use cdist, you'll write a type for every functionality you would like
|
||||
to use.
|
||||
|
||||
Synopsis
|
||||
--------
|
||||
|
||||
HOW TO USE A TYPE
|
||||
.. code-block:: sh
|
||||
|
||||
__TYPE ID --parameter value [--parameter value ...]
|
||||
__TYPE --parameter value [--parameter value ...] (for singletons)
|
||||
|
||||
|
||||
How to use a type
|
||||
-----------------
|
||||
|
||||
You can use types from the initial manifest or the type manifest like a
|
||||
normal shell command:
|
||||
|
||||
|
|
@ -37,10 +30,10 @@ normal shell command:
|
|||
# Ensure tree is installed
|
||||
__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 <cdist-reference.html>`_ manpage.
|
||||
|
||||
|
||||
SINGLETON TYPES
|
||||
Singleton types
|
||||
---------------
|
||||
If a type is flagged as a singleton, it may be used only
|
||||
once per host. This is useful for types which can be used only once on a
|
||||
|
|
@ -58,7 +51,7 @@ Example:
|
|||
__myfancysingleton --colour green
|
||||
|
||||
|
||||
HOW TO WRITE A NEW TYPE
|
||||
How to write a new type
|
||||
-----------------------
|
||||
A type consists of
|
||||
|
||||
|
|
@ -74,7 +67,7 @@ two underscores (__) to prevent collisions with other executables in $PATH.
|
|||
To implement a new type, create the directory **cdist/conf/type/__NAME**.
|
||||
|
||||
|
||||
DEFINING PARAMETERS
|
||||
Defining parameters
|
||||
-------------------
|
||||
Every type consists of required, optional and boolean parameters, which must
|
||||
each be declared in a newline separated file in **parameter/required**,
|
||||
|
|
@ -102,7 +95,7 @@ Example:
|
|||
echo use_ssl >> cdist/conf/type/__nginx_vhost/parameter/boolean
|
||||
|
||||
|
||||
USING PARAMETERS
|
||||
Using parameters
|
||||
----------------
|
||||
The parameters given to a type can be accessed and used in all type scripts
|
||||
(e.g manifest, gencode, explorer). Note that boolean parameters are
|
||||
|
|
@ -138,7 +131,7 @@ Example: (e.g. in cdist/conf/type/__nginx_vhost/manifest)
|
|||
fi
|
||||
|
||||
|
||||
INPUT FROM STDIN
|
||||
Input from stdin
|
||||
----------------
|
||||
Every type can access what has been written on stdin when it has been called.
|
||||
The result is saved into the **stdin** file in the object directory.
|
||||
|
|
@ -168,7 +161,7 @@ In the __file type, stdin is used as source for the file, if - is used for sourc
|
|||
....
|
||||
|
||||
|
||||
WRITING THE MANIFEST
|
||||
Writing the manifest
|
||||
--------------------
|
||||
In the manifest of a type you can use other types, so your type extends
|
||||
their functionality. A good example is the __package type, which in
|
||||
|
|
@ -190,13 +183,13 @@ a shortened version looks like this:
|
|||
__package_$type "$@"
|
||||
|
||||
As you can see, the type can reference different environment variables,
|
||||
which are documented in cdist-reference(7).
|
||||
which are documented in `cdist reference <cdist-reference.html>`_.
|
||||
|
||||
Always ensure the manifest is executable, otherwise cdist will not be able
|
||||
to execute it. For more information about manifests see cdist-manifest(7).
|
||||
to execute it. For more information about manifests see `cdist manifest <cdist-manifest.html>`_.
|
||||
|
||||
|
||||
SINGLETON - ONE INSTANCE ONLY
|
||||
Singleton - one instance only
|
||||
-----------------------------
|
||||
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
|
||||
|
|
@ -216,7 +209,7 @@ As you can see, the object ID is omitted, because it does not make any sense,
|
|||
if your type can be used only once.
|
||||
|
||||
|
||||
THE TYPE EXPLORERS
|
||||
The type explorers
|
||||
------------------
|
||||
If a type needs to explore specific details, it can provide type specific
|
||||
explorers, which will be executed on the target for every created object.
|
||||
|
|
@ -238,7 +231,7 @@ client, like this (shortened version from the type __file):
|
|||
fi
|
||||
|
||||
|
||||
WRITING THE GENCODE SCRIPT
|
||||
Writing the gencode script
|
||||
--------------------------
|
||||
There are two gencode scripts: **gencode-local** and **gencode-remote**.
|
||||
The output of gencode-local is executed locally, whereas
|
||||
|
|
@ -259,7 +252,7 @@ script, you can write to stderr:
|
|||
echo "touch /etc/cdist-configured"
|
||||
|
||||
|
||||
VARIABLE ACCESS FROM THE GENERATED SCRIPTS
|
||||
Variable access from the generated scripts
|
||||
------------------------------------------
|
||||
In the generated scripts, you have access to the following cdist variables
|
||||
|
||||
|
|
@ -280,7 +273,7 @@ So when you generate a script with the following content, it will work:
|
|||
fi
|
||||
|
||||
|
||||
HINTS FOR TYPEWRITERS
|
||||
Hints for typewriters
|
||||
----------------------
|
||||
It must be assumed that the target is pretty dumb and thus does not have high
|
||||
level tools like ruby installed. If a type requires specific tools to be present
|
||||
|
|
@ -297,21 +290,8 @@ a folder named "files" within the type (again, because cdist guarantees to
|
|||
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
|
||||
current master branch of cdist and have a look at cdist-hacker(7) on
|
||||
current master branch of cdist and have a look at `cdist hacking <cdist-hacker.html>`_ on
|
||||
how to submit it.
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist-explorer(7) <cdist-explorer.html>`_
|
||||
- `cdist-hacker(7) <cdist-hacker.html>`_
|
||||
- `cdist-stages(7) <cdist-stages.html>`_
|
||||
- `cdist-tutorial(7) <cdist-tutorial.html>`_
|
||||
|
||||
|
||||
COPYING
|
||||
-------
|
||||
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).
|
||||
8
docs/man/cdist-types.rst
Normal file
8
docs/man/cdist-types.rst
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
cdist types
|
||||
===========
|
||||
|
||||
.. toctree::
|
||||
:titlesonly:
|
||||
:glob:
|
||||
|
||||
man7/*
|
||||
188
docs/man/cdist-update.rst
Normal file
188
docs/man/cdist-update.rst
Normal file
|
|
@ -0,0 +1,188 @@
|
|||
How to update cdist
|
||||
===================
|
||||
|
||||
Update the git installation
|
||||
---------------------------
|
||||
|
||||
To upgrade cdist in the current branch use
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
git pull
|
||||
|
||||
# Also update the manpages
|
||||
./build man
|
||||
export MANPATH=$MANPATH:$(pwd -P)/doc/man
|
||||
|
||||
If you stay on a version branche (i.e. 1.0, 1.1., ...), nothing should break.
|
||||
The master branch on the other hand is the development branch and may not be
|
||||
working, break your setup or eat the tree in your garden.
|
||||
|
||||
Safely upgrading to new versions
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To upgrade to **any** further cdist version, you can take the
|
||||
following procedure to do a safe upgrade:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
# Create new branch to try out the update
|
||||
git checkout -b upgrade_cdist
|
||||
|
||||
# Get latest cdist version in git database
|
||||
git fetch -v
|
||||
|
||||
# see what will happen on merge - replace
|
||||
# master with the branch you plan to merge
|
||||
git diff upgrade_cdist..origin/master
|
||||
|
||||
# Merge the new version
|
||||
git merge origin/master
|
||||
|
||||
Now you can ensure all custom types work with the new version.
|
||||
Assume that you need to go back to an older version during
|
||||
the migration/update, you can do so as follows:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
# commit changes
|
||||
git commit -m ...
|
||||
|
||||
# go back to original branch
|
||||
git checkout master
|
||||
|
||||
After that, you can go back and continue the upgrade:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
# git checkout upgrade_cdist
|
||||
|
||||
|
||||
Update the python package
|
||||
-------------------------
|
||||
|
||||
To upgrade to the lastet version do
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
pip install --upgrade cdist
|
||||
|
||||
General update instructions
|
||||
---------------------------
|
||||
|
||||
Updating from 3.0 to 3.1
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The type **\_\_ssh_authorized_keys** now also manages existing keys,
|
||||
not only the ones added by cdist.
|
||||
|
||||
Updating from 2.3 to 3.0
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The **changed** attribute of objects has been removed.
|
||||
Use `messaging </software/cdist/man/3.0.0/man7/cdist-messaging.html>`_ instead.
|
||||
|
||||
Updating from 2.2 to 2.3
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
No incompatiblities.
|
||||
|
||||
Updating from 2.1 to 2.2
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Starting with 2.2, the syntax for requiring a singleton type changed:
|
||||
Old format:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
require="__singleton_type/singleton" ...
|
||||
|
||||
New format:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
require="__singleton_type" ...
|
||||
|
||||
Internally the "singleton" object id was dropped to make life more easy.
|
||||
You can probably fix your configuration by running the following code
|
||||
snippet (currently untested, please report back if it works for you):
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
find ~/.cdist/* -type f -exec sed -i 's,/singleton,,' {} \;
|
||||
|
||||
Updating from 2.0 to 2.1
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Have a look at the update guide for [[2.0 to 2.1|2.0-to-2.1]].
|
||||
|
||||
* Type **\_\_package* and \_\_process** use --state **present** or **absent**.
|
||||
The states **removed/installed** and **stopped/running** have been removed.
|
||||
Support for the new states is already present in 2.0.
|
||||
* Type **\_\_directory**: Parameter --parents and --recursive are now boolean
|
||||
The old "yes/no" values need to be removed.
|
||||
* Type **\_\_rvm_ruby**: Parameter --default is now boolean
|
||||
The old "yes/no" values need to be removed.
|
||||
* Type **\_\_rvm_gemset**: Parameter --default is now boolean
|
||||
The old "yes/no" values need to be removed.
|
||||
* Type **\_\_addifnosuchline** and **\_\_removeline** have been replaced by **\_\_line**
|
||||
* The **conf** directory is now located at **cdist/conf**.
|
||||
You need to migrate your types, explorers and manifests
|
||||
manually to the new location.
|
||||
* Replace the variable **\_\_self** by **\_\_object_name**
|
||||
Support for the variable **\_\_object_name** is already present in 2.0.
|
||||
* The types **\_\_autofs**, **\_\_autofs_map** and **\_\_autofs_reload** have been removed
|
||||
(no maintainer, no users)
|
||||
* Type **\_\_user**: Parameter --groups removed (use the new \_\_user_groups type)
|
||||
* Type **\_\_ssh_authorized_key** has been replaced by more flexible type
|
||||
**\_\_ssh_authorized_keys**
|
||||
|
||||
Updating from 1.7 to 2.0
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* Ensure python (>= 3.2) is installed on the source host
|
||||
* Use "cdist config host" instead of "cdist-deploy-to host"
|
||||
* Use "cdist config -p host1 host2" instead of "cdist-mass-deploy"
|
||||
* Use "cdist banner" for fun
|
||||
* Use **\_\_object_name** instead of **\_\_self** in manifests
|
||||
|
||||
Updating from 1.6 to 1.7
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* If you used the global explorer **hardware_type**, you need to change
|
||||
your code to use **machine** instead.
|
||||
|
||||
Updating from 1.5 to 1.6
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* If you used **\_\_package_apt --preseed**, you need to use the new
|
||||
type **\_\_debconf_set_selections** instead.
|
||||
* The **\_\_package** types accepted either --state deinstalled or
|
||||
--state uninstaaled. Starting with 1.6, it was made consistently
|
||||
to --state removed.
|
||||
|
||||
Updating from 1.3 to 1.5
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
No incompatiblities.
|
||||
|
||||
Updating from 1.2 to 1.3
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Rename **gencode** of every type to **gencode-remote**.
|
||||
|
||||
Updating from 1.1 to 1.2
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
No incompatiblities.
|
||||
|
||||
Updating from 1.0 to 1.1
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In 1.1 the type **\_\_file** was split into **\_\_directory**, **\_\_file** and
|
||||
**\_\_link**. The parameter **--type** was removed from **\_\_file**. Thus you
|
||||
need to replace **\_\_file** calls in your manifests:
|
||||
|
||||
* Remove --type from all \_\_file calls
|
||||
* If type was symlink, use \_\_link and --type symbolic
|
||||
* If type was directory, use \_\_directory
|
||||
72
docs/man/cdist-why.rst
Normal file
72
docs/man/cdist-why.rst
Normal file
|
|
@ -0,0 +1,72 @@
|
|||
Why should I use cdist?
|
||||
=======================
|
||||
|
||||
There are several motivations to use cdist, these
|
||||
are probably the most popular ones.
|
||||
|
||||
Known language
|
||||
--------------
|
||||
|
||||
Cdist is being configured in
|
||||
`shell script <https://en.wikipedia.org/wiki/Shell_script>`_.
|
||||
Shell script is used by UNIX system engineers for decades.
|
||||
So when cdist is introduced, your staff does not need to learn a new
|
||||
`DSL <https://en.wikipedia.org/wiki/Domain-specific_language>`_
|
||||
or programming language.
|
||||
|
||||
Powerful language
|
||||
-----------------
|
||||
|
||||
Not only is shell scripting widely known by system engineers,
|
||||
but it is also a very powerful language. Here are some features
|
||||
which make daily work easy:
|
||||
|
||||
* Configuration can react dynamicly on explored values
|
||||
* High level string manipulation (using sed, awk, grep)
|
||||
* Conditional support (**if, case**)
|
||||
* Loop support (**for, while**)
|
||||
* Support for dependencies between cdist types
|
||||
|
||||
More than shell scripting
|
||||
-------------------------
|
||||
|
||||
If you compare regular shell scripting with cdist, there is one major
|
||||
difference: When using cdist types,
|
||||
the results are
|
||||
`idempotent <https://en.wikipedia.org/wiki/Idempotence>`_.
|
||||
In practise that means it does not matter in which order you
|
||||
call cdist types, the result is always the same.
|
||||
|
||||
Zero dependency configuration management
|
||||
----------------------------------------
|
||||
|
||||
Cdist requires very litte 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
|
||||
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,
|
||||
it does not require to open up an additional port.
|
||||
|
||||
Push based distribution
|
||||
-----------------------
|
||||
|
||||
Cdist uses the push based model for configuration. In this
|
||||
scenario, one (or more) computers connect 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
|
||||
limited amount of resources.
|
||||
|
||||
Furthermore, from a security point of view, only one machine
|
||||
needs access to the target hosts. No target hosts will ever
|
||||
need to connect back to the source host, which contains the
|
||||
full configuration.
|
||||
|
||||
Highly scalable
|
||||
---------------
|
||||
|
||||
If at some point you manage more hosts than can be handled from
|
||||
a single source host, you can simply add more resources: Either
|
||||
add more cores to one host or add hosts.
|
||||
Cdist will utilise the given resources in parallel.
|
||||
|
|
@ -32,6 +32,7 @@ sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(os.path.realpath
|
|||
# ones.
|
||||
extensions = [
|
||||
'cdist.sphinxext.manpage',
|
||||
'sphinx.ext.extlinks',
|
||||
]
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
|
|
@ -309,3 +310,9 @@ texinfo_documents = [
|
|||
|
||||
# If true, do not generate a @detailmenu in the "Top" node's menu.
|
||||
#texinfo_no_detailmenu = False
|
||||
|
||||
extlinks = {
|
||||
'cdist_docs':
|
||||
('http://www.nico.schottelius.org/software/cdist/man/{}/%s.html'.format(
|
||||
release), None),
|
||||
}
|
||||
|
|
|
|||
|
|
@ -4,9 +4,28 @@ Welcome to cdist documentation
|
|||
Contents:
|
||||
|
||||
.. toctree::
|
||||
:titlesonly:
|
||||
:maxdepth: 2
|
||||
:glob:
|
||||
:numbered:
|
||||
|
||||
man1/*
|
||||
man7/*
|
||||
cdist-intro
|
||||
cdist-why
|
||||
cdist-os
|
||||
cdist-install
|
||||
cdist-update
|
||||
cdist-support
|
||||
cdist-features
|
||||
cdist-quickstart
|
||||
man1/cdist
|
||||
cdist-bootstrap
|
||||
cdist-manifest
|
||||
cdist-type
|
||||
cdist-types
|
||||
cdist-explorer
|
||||
cdist-messaging
|
||||
cdist-reference
|
||||
cdist-best-practice
|
||||
cdist-stages
|
||||
cdist-remote-exec-copy
|
||||
cdist-hacker
|
||||
cdist-troubleshooting
|
||||
|
|
|
|||
|
|
@ -5,8 +5,6 @@ NAME
|
|||
----
|
||||
cdist - Usable Configuration Management
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
|
|
@ -179,9 +177,11 @@ The following exit values shall be returned:
|
|||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist-type(7) <../man7/cdist-type.html>`_
|
||||
- `cdist-reference(7) <../man7/cdist-reference.html>`_
|
||||
Full documentation at: <:cdist_docs:`index`>.
|
||||
|
||||
AUTHORS
|
||||
-------
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
COPYING
|
||||
-------
|
||||
|
|
|
|||
|
|
@ -1,58 +0,0 @@
|
|||
cdist-tutorial(7)
|
||||
=================
|
||||
|
||||
NAME
|
||||
----
|
||||
cdist-tutorial - A guided introduction into cdist
|
||||
|
||||
Nico Schottelius <nico-cdist--@--schottelius.org>
|
||||
|
||||
|
||||
INTRODUCTION
|
||||
------------
|
||||
This document gives you a pointer on what to read in
|
||||
which order and is thus a "guide to the right locations".
|
||||
So in case you are just starting, just "begin at the beginning"
|
||||
(Brave New World). You can see the target audience in [] brackets
|
||||
after the description.
|
||||
|
||||
cdist-quickstart
|
||||
New to cdist? Want to get your hands dirty? Read this. [beginner]
|
||||
|
||||
cdist-bootstrap
|
||||
The comprehensive guide to your first cdist installation [beginner]
|
||||
|
||||
cdist-manifest
|
||||
Learn how to define which hosts get which configurations [beginner]
|
||||
|
||||
cdist-type
|
||||
Understand how types are working and created [intermediate]
|
||||
|
||||
cdist-best-practice
|
||||
Hints from real life experience to help you to organise cdist [intermediate]
|
||||
|
||||
cdist-reference
|
||||
The type, explorers and environment variables reference [intermediate]
|
||||
|
||||
cdist-explorer
|
||||
Interested in getting more information about the target system? [intermediate]
|
||||
|
||||
cdist-stages
|
||||
Understand the internal workflow of cdist. [advanced]
|
||||
|
||||
cdist-hacker
|
||||
README, if you want to extend or modify cdist. [hacker]
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
- `cdist(1) <../man1/cdist.html>`_
|
||||
- `cdist-type(7) <cdist-type.html>`_
|
||||
- `cdist-best-practice(7) <cdist-best-practice.html>`_
|
||||
- `cdist-stages(7) <cdist-stages.html>`_
|
||||
- Brave New World by Aldous Huxley
|
||||
|
||||
COPYING
|
||||
-------
|
||||
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).
|
||||
Loading…
Add table
Add a link
Reference in a new issue