fnux/cdist-web
1
0
Fork 0
forked from ungleich-public/cdist-web
Code Issues Pull requests Projects Releases Wiki Activity

Release cdist 6.3.0

Browse source
This commit is contained in:
Darko Poljak 2019-12-12 07:52:15 +01:00
parent 54c726b7d4
commit 3637869480
433 changed files with 118885 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
src/cdist-changelog.rst
View file

@ -1,6 +1,18 @@
Changelog
---------
6.3.0: 2019-12-12
~~~~~~~~~~~~~~~~~
* Type __package_update_index: Fix Alpine part (Dominique Roux)
* Documentation: Fix man pages for install types (Darko Poljak)
* Documentation: Embed config skeleton instead of rewriting it (Darko Poljak)
* Documentation: Remove cdist-type prefix and man page reference from type list in html (Darko Poljak)
* Documentation: PreOS english nitpicking (Evil Ham)
* Documentation: Add installing from source with signature verification (Darko Poljak)
* Core: preos: Support top command logging options, custom conf-dir option and CDIST_PATH env var (Darko Poljak)
* Type __start_on_boot: Docs: remove unsupported *BSD claim (Evil Ham)
* New type: __openldap_server (Evil Ham)
6.2.0: 2019-11-30
~~~~~~~~~~~~~~~~~
* Core: Redefine/reimplement/fix CDIST_ORDER_DEPENDENCY (Darko Poljak)

1
src/cdist-manual.rst
View file

@ -8,6 +8,7 @@ cdist manual
**All versions**
* `6.3.0 <manual/6.3.0>`_
* `6.2.0 <manual/6.2.0>`_
* `6.1.1 <manual/6.1.1>`_
* `6.1.0 <manual/6.1.0>`_

4
src/extra/manual/6.3.0/.buildinfo Normal file
View file

@ -0,0 +1,4 @@
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config: 30ac008f014a954ad842e650bda061fc
tags: 645f666f9bcd5a90fca523b33c5a78b7

278
src/extra/manual/6.3.0/_sources/cdist-best-practice.rst.txt Normal file
View file

@ -0,0 +1,278 @@
Best practice
=============
Practices used in real environments
Passwordless connections
------------------------
It is recommended to run cdist with public key authentication.
This requires a private/public key pair and the entry
"PermitRootLogin without-password" in the sshd server.
See sshd_config(5) and ssh-keygen(1).
Speeding up ssh connections
---------------------------
When connecting to a new host, the initial delay with ssh connections
is pretty big. As cdist makes many connections to each host successive
connections can be sped up by "sharing of multiple sessions over a single
network connection" (quote from ssh_config(5)). This is also called "connection
multiplexing".
Cdist implements this since v4.0.0 by executing ssh with the appropriate
options (`-o ControlMaster=auto -o ControlPath=/tmp/<tmpdir>/s -o
ControlPersist=2h`).
Note that the sshd_config on the server can configure the maximum number of
parallel multiplexed connections this with `MaxSessions N` (N defaults to 10
for OpenSSH v7.4).
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::
ln -sf /bin/dash /bin/sh
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
control git. For instance if you plan to use the typical three
environments production, integration and development, you can
realise this with git branches::
# Go to cdist checkout
cd /path/to/cdist
# Create branches
git branch development
git branch integration
git branch production
# Make use of a branch, for instance production
git checkout production
Similar if you want to have cdist checked out at multiple machines,
you can clone it multiple times::
machine-a % git clone git://your-git-server/cdist
machine-b % git clone git://your-git-server/cdist
Separating 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
their manifests. You can use the following snippet in
**conf/manifests/init**::
# Include other groups
sh -e "$__manifest/systems"
sh -e "$__manifest/cbrg"
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.
Including a possible common base that is reused across the different sites::
# create branches
git branch company_a company_b common private
# make stuff for company a
git checkout company_a
# work, commit, etc.
# make stuff for company b
git checkout company_b
# work, commit, etc.
# make stuff relevant for all sites
git checkout common
# work, commit, etc.
# change to private and include latest common stuff
git checkout private
git merge common
The following **.git/config** is taken from a real world scenario::
# Track upstream, merge from time to time
[remote "upstream"]
url = git://git.schottelius.org/cdist
fetch = +refs/heads/*:refs/remotes/upstream/*
# Same as upstream, but works when being offline
[remote "local"]
fetch = +refs/heads/*:refs/remotes/local/*
url = /home/users/nico/p/cdist
# Remote containing various ETH internal branches
[remote "eth"]
url = sans.ethz.ch:/home/services/sans/git/cdist-eth
fetch = +refs/heads/*:refs/remotes/eth/*
# Public remote that contains my private changes to cdist upstream
[remote "nico"]
url = git.schottelius.org:/home/services/git/cdist-nico
fetch = +refs/heads/*:refs/remotes/nico/*
# The "nico" branch will be synced with the remote nico, branch master
[branch "nico"]
remote = nico
merge = refs/heads/master
# ETH stable contains rock solid configurations used in various places
[branch "eth-stable"]
remote = eth
merge = refs/heads/stable
Have a look at git-remote(1) to adjust the remote configuration, which allows
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
implement this scenario with a gateway host and sudo:
- Create a dedicated user (for instance **cdist**)
- 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 basis.
- f.i. nico ALL=(ALL) NOPASSWD: /home/cdist/bin/cdist config hostabc
For more details consult sudoers(5)
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
.. code-block:: sh
#!/bin/sh
# in the template, use cat << eof (here document) to output the text
# and use standard shell variables in the template
# output everything in the template script to stdout
cat << EOF
server {
listen 80;
server_name $SERVERNAME;
root $ROOT;
access_log /var/log/nginx/$SERVERNAME_access.log
error_log /var/log/nginx/$SERVERNAME_error.log
}
EOF
* in the manifest, export the relevant variables and add the following lines to your manifest:
.. code-block:: console
# export variables needed for the template
export SERVERNAME='test"
export ROOT='/var/www/test'
# render the template
mkdir -p "$__object/files"
"$__type/files/basic.conf.sh" > "$__object/files/basic.conf"
# send the rendered template
__file /etc/nginx/sites-available/test.conf \
--state present
--source "$__object/files/basic.conf"
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
with - (stdin) as argument and feed object into stdin
of cdist:
.. code-block:: sh
# Singleton type without parameter
echo __ungleich_munin_server | cdist --initial-manifest - munin.panter.ch
# Singleton type with parameter
echo __ungleich_munin_node --allow 1.2.3.4 | \
cdist --initial-manifest - rails-19.panter.ch
# Normal type
echo __file /tmp/stdintest --mode 0644 | \
cdist --initial-manifest - cdist-dev-01.ungleich.ch
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
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 is not
and also to store all important files in one
repository.
Notes on CDIST_ORDER_DEPENDENCY
-------------------------------
With CDIST_ORDER_DEPENDENCY all types are executed in the order in which they
are created in the manifest. The current created object automatically depends
on the previously created object.
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).
This can be helpful, but one must be aware of its side effects.
CDIST_ORDER_DEPENDENCY kills parallelization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Suppose you have defined CDIST_ORDER_DEPENDENCY and then, among other things,
you specify creation of three, by nature independent, files.
**init**
.. code-block:: sh
CDIST_ORDER_DEPENDENCY=1
export CDIST_ORDER_DEPENDENCY
...
__file /tmp/file1
__file /tmp/file2
__file /tmp/file3
...
Due to defined CDIST_ORDER_DEPENDENCY cdist will execute them in specified order.
It is better to use CDIST_ORDER_DEPENDENCY in well defined blocks:
**init**
.. code-block:: sh
CDIST_ORDER_DEPENDENCY=1
export CDIST_ORDER_DEPENDENCY
...
unset CDIST_ORDER_DEPENDENCY
__file /tmp/file1
__file /tmp/file2
__file /tmp/file3
CDIST_ORDER_DEPENDENCY=1
export CDIST_ORDER_DEPENDENCY
...
unset CDIST_ORDER_DEPENDENCY

118
src/extra/manual/6.3.0/_sources/cdist-bootstrap.rst.txt Normal file
View file

@ -0,0 +1,118 @@
Bootstrap
=========
This document describes the usual steps recommended for a new
cdist setup. It is recommended that you have read and understood
`cdist quickstart <cdist-quickstart.html>`_ before digging into this.
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
think about where to configure your hosts from, which may be a different
location.
For starters, having cdist (which includes the configuration database) on
your notebook should be fine.
Additionally an external copy of the git repository the configuration
relies on is recommended, for use as backup as well as to allow easy collaboration
with others.
For more sophisticated setups developing cdist configurations with multiple
people, have a look at `cdist best practice <cdist-best-practice.html>`_.
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 <cdist-quickstart.html>`_ if you don't).
Entering the command "git branch" should show you "* master", which indicates
you are on the **master** branch.
The master branch reflects the latest development of cdist. As this is the
development branch, it may or may not work. There are also version branches
available, which are kept in a stable state. Let's use **git branch -r**
to list all branches::
cdist% git branch -r
origin/1.0
origin/1.1
origin/1.2
origin/1.3
origin/1.4
origin/1.5
origin/1.6
origin/1.7
origin/2.0
origin/HEAD -> origin/master
origin/archive_shell_function_approach
origin/master
So **2.0** is the latest version branch in this example.
All versions (2.0.x) within one version branch (2.0) are compatible to each
other and won't break your configuration when updating.
It's up to you to decide which branch you want to base your own work on:
master contains more recent changes, newer types, but may also break.
The version branches are stable, but may lack the latest features.
Your decision can be changed later on, but may result in merge conflicts,
which you will need to solve.
Let's assume you want latest stuff and select the master branch as base for
your own work. Now it's time to create your branch, which contains your
local changes. I usually name it by the company/area I am working for:
ethz-systems, localch, customerX, ... But this is pretty much up to you.
In this tutorial I use the branch **mycompany**::
cdist% git checkout -b mycompany origin/master
Branch mycompany set up to track remote branch master from origin.
Switched to a new branch 'mycompany'
cdist-user% git branch
master
* mycompany
From now on, you can use git as usual to commit your changes in your own branch.
Publishing the configuration
----------------------------
Usually a development machine like a notebook should be considered
temporary only. For this reason and to enable shareability, the configuration
should be published to another device as early as possible. The following
example shows how to publish the configuration to another host that is
reachable via ssh and has git installed::
# Create bare git repository on the host named "loch"
cdist% ssh loch "GIT_DIR=/home/nutzer/cdist git init"
Initialized empty Git repository in /home/nutzer/cdist/
# Add remote git repo to git config
cdist% git remote add loch loch:/home/nutzer/cdist
# Configure the mycompany branch to push to loch
cdist% git config branch.mycompany.remote loch
# Configure mycompany branch to push into remote master branch
cdist% git config branch.mycompany.merge refs/heads/master
# Push mycompany branch to remote branch master initially
cdist% git push loch mycompany:refs/heads/master
Now you have setup the git repository to synchronise the **mycompany**
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
--------------------
Whenever you want to update your cdist installation, you can use git to do so::
# Update git repository with latest changes from origin
cdist% git fetch origin
# Update current branch with master branch from origin
cdist% git merge origin/master
# Alternative: Update current branch with 2.0 branch from origin
cdist% git merge origin/2.0

98
src/extra/manual/6.3.0/_sources/cdist-cache.rst.txt Normal file
View file

@ -0,0 +1,98 @@
Local cache overview
====================
Description
-----------
While executing, cdist stores data to local cache. Currently this feature is
one way only. That means that cdist does not use stored data for future runs.
Anyway, those data can be used for debugging cdist, debugging types and
debugging after host configuration fails.
Local cache is saved under $HOME/.cdist/cache directory, one directory entry
for each host. Subdirectory path is specified by
:strong:`-C/--cache-path-pattern` option, :strong:`cache_path_pattern`
configuration option or by using :strong:`CDIST_CACHE_PATH_PATTERN`
environment variable.
For more info on cache path pattern see :strong:`CACHE PATH PATTERN FORMAT`
section in cdist man page.
Cache overview
--------------
As noted above each configured host has got its subdirectory in local cache.
Entries in host's cache directory are as follows.
bin
directory with cdist type emulators
conf
dynamically determined cdist conf directory, union of all specified
conf directories
explorer
directory containing global explorer named files containing explorer output
after running on target host
messages
file containing messages
object
directory containing subdirectory for each cdist object
object_marker
object marker for this particular cdist run
stderr
directory containing init manifest and remote stderr stream output
stdout
directory containing init manifest and remote stdout stream output
target_host
file containing target host of this cdist run, as specified when running
cdist
typeorder
file containing types in order of execution.
Object cache overview
~~~~~~~~~~~~~~~~~~~~~
Each object under :strong:`object` directory has its own structurue.
code-local
code generated from gencode-local, present only if something is
generated
code-remote
code generated from gencode-remote, present only if something is
generated
explorer
directory containing type explorer named files containing explorer output
after running on target host
files
directory with object files created during type execution
parameter
directory containing type parameter named files containing parameter
values
source
this type's source (init manifest)
state
this type execution state ('done' when finished)
stderr
directory containing type's manifest, gencode-* and code-* stderr stream
outputs
stdin
this type stdin content
stdout
directory containing type's manifest, gencode-* and code-* stdout stream
outputs.

41
src/extra/manual/6.3.0/_sources/cdist-configuration.rst.txt Normal file
View file

@ -0,0 +1,41 @@
Configuration
=============
Description
-----------
cdist obtains configuration data from the following sources in the following
order:
#. command-line options
#. configuration file specified at command-line using -g command line option
#. configuration file specified in CDIST_CONFIG_FILE environment variable
#. environment variables
#. user's configuration file (first one found of ~/.cdist.cfg, $XDG_CONFIG_HOME/cdist/cdist.cfg, in specified order)
#. in-distribution configuration file (cdist/conf/cdist.cfg)
#. system-wide configuration file (/etc/cdist.cfg)
if one exists.
Configuration source with lower ordering number from above has a higher
precedence. Configuration option value read from source with higher
precedence will overwrite option value, if exists, read from source with
lower precedence. That means that command-line option wins them all.
Users can decide on the local conifguration file location. It can be either
~/.cdist.cfg or $XDG_CONFIG_HOME/cdist/cdist.cfg. Note that, if both exist,
then ~/.cdist.cfg is used.
For a per-project configuration, particular environment variables or better,
CDIST_CONFIG_FILE environment variable or -g CONFIG_FILE command line option,
can be used.
Config file format
------------------
cdist configuration file is in the INI file format. Currently it supports
only [GLOBAL] section.
Here you can find configuration file skeleton:
.. literalinclude:: cdist.cfg.skeleton
:language: ini

54
src/extra/manual/6.3.0/_sources/cdist-explorer.rst.txt Normal file
View file

@ -0,0 +1,54 @@
Explorer
========
Description
-----------
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.
There are general explorers, which are run in an early stage, and
type explorers. Both work almost exactly the same way, with the difference
that the values of the general explorers are stored in a general location and
the type specific below the object.
Explorers can reuse other explorers on the target system by calling
::
$__explorer/<explorer_name> (general and type explorer)
or
::
$__type_explorer/<explorer name> (type explorer).
In case of significant errors, the explorer may exit non-zero and return an
error message on stderr, which will cause cdist to abort.
You can also use stderr for debugging purposes while developing a new
explorer.
Examples
--------
A very simple explorer may look like this::
hostname
Which is in practise the **hostname** explorer.
A type explorer, which could check for the status of a package may look like this:
.. code-block:: sh
if [ -f "$__object/parameter/name" ]; then
name="$(cat "$__object/parameter/name")"
else
name="$__object_id"
fi
# Expect dpkg failing, if package is not known / installed
dpkg -s "$name" 2>/dev/null || exit 0

48
src/extra/manual/6.3.0/_sources/cdist-features.rst.txt Normal file
View 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 separated
+ 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
+ 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, familiar environment, documentation
Is available as manpages and HTML
UNIX, simplicity, familiar environment
cdist is configured in POSIX shell

145
src/extra/manual/6.3.0/_sources/cdist-hacker.rst.txt Normal file
View file

@ -0,0 +1,145 @@
Hacking
=======
Welcome
-------
Welcome dear hacker! I invite you to a tour of pointers to
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
twice before merging or implementing a feature: Less features
with good usability are far better than the opposite.
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 code.ungleich.ch.
Coding conventions (everywhere)
-------------------------------
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.
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 think might be of benefit to other
cdist users, you're welcome to propose inclusion into upstream.
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.)
- Code submission must be done via git
- Do not add cdist/conf/manifest/init - This file should only be touched in your
private branch!
- Code to be included should be branched of the upstream "master" branch
- Exception: Bugfixes to a version branch
- On a merge request, always name the branch I should pull from
- Always ensure **all** manpages build. Use **./build man** to test.
- If you developed more than **one** feature, consider submitting them in
separate branches. This way one feature can already be included, even if
the other needs to be improved.
As soon as your work meets these requirements, write a mail
for inclusion to the mailinglist **cdist-configuration-management at googlegroups.com**
or open a merge request at https://code.ungleich.ch/ungleich-public/cdist.
How to submit a new type
------------------------
For detailed 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.rst in ReSTructured text format with
the manpage-name "cdist-type__NAME" is included in the type directory
AND the manpage builds (`make man`).
Warning: Submitting "exec" or "run" types that simply echo their parameter in
**gencode** will not be accepted, because they are of no use. Every type can output
code and thus such a type introduces redundant functionality that is given by
core cdist already.
Example git workflow
---------------------
The following workflow works fine for most developers
.. code-block:: sh
# get latest upstream master branch
git clone https://code.ungleich.ch/ungleich-public/cdist.git
# update if already existing
cd cdist; git fetch -v; git merge origin/master
# create a new branch for your feature/bugfix
cd cdist # if you haven't done before
git checkout -b documentation_cleanup
# *hack*
*hack*
# clone the cdist repository on code.ungleich.ch if you haven't done so
# configure your repo to know about your clone (only once)
git remote add ungleich git@code.ungleich.ch:YOURUSERNAME/cdist.git
# push the new branch to ungleich gitlab
git push ungleich documentation_cleanup
# (or everything)
git push --mirror ungleich
# create a merge request at ungleich gitlab (use a browser)
# *fixthingsbecausequalityassurancefoundissuesinourpatch*
*hack*
# push code to ungleich gitlab again
git push ... # like above
# add comment that everything should be green now (use a browser)
# go back to master branch
git checkout master
# update master branch that includes your changes now
git fetch -v origin
git diff master..origin/master
git merge origin/master
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
# change to master and update to most recent upstream version
git checkout master
git fetch -v origin
git merge origin/master
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
# change to master and update to most recent upstream version
git checkout master
git fetch -v origin
git merge origin/master
git checkout -b another_feature
(you can repeat the code above for as many features as you want to develop
in parallel)

182
src/extra/manual/6.3.0/_sources/cdist-install.rst.txt Normal file
View file

@ -0,0 +1,182 @@
How to install cdist
====================
Requirements
-------------
Source Host
~~~~~~~~~~~
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
* SSH client
* sphinx (for building html docs and/or the man pages)
Target Hosts
~~~~~~~~~~~~
* /bin/sh: A posix like shell (for instance bash, dash, zsh)
* SSH server
Install cdist
-------------
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://code.ungleich.ch/ungleich-public/cdist.git
cd cdist
export PATH=$PATH:$(pwd -P)/bin
From version 4.2.0 cdist tags and releases are signed.
You can get GPG public key used for signing `here <_static/pgp-key-EFD2AE4EC36B6901.asc>`_.
It is assumed that you are familiar with *git* ways of signing and verification.
You can also get cdist from `github mirror <https://github.com/ungleich/cdist>`_.
To install cdist with distutils from cloned repository, first you have to
create version.py:
.. code-block:: sh
./bin/build-helper version
Then you install it with:
.. code-block:: sh
make install
or with:
.. code-block:: sh
make install-user
to install it into user *site-packages* directory.
Or directly with distutils:
.. code-block:: sh
python setup.py install
Note that `bin/build-helper` script is intended for cdist maintainers.
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
Building and using documentation (man and html)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you want to build and use the documentation, run:
.. code-block:: sh
make docs
Documentation comes in two formats, man pages and full HTML
documentation. Documentation is built into distribution's
docs/dist directory. man pages are in docs/dist/man and
HTML documentation in docs/dist/html.
If you want to use man pages, run:
.. code-block:: sh
export MANPATH=$MANPATH:$(pwd -P)/docs/dist/man
Or you can move man pages from docs/dist/man directory to some
other directory and add it to MANPATH.
Full HTML documentation can be accessed at docs/dist/html/index.html.
You can also build only man pages or only html documentation, for
only man pages run:
.. code-block:: sh
make man
for only html documentation run:
.. code-block:: sh
make html
You can also build man pages for types in your ~/.cdist directory:
.. code-block:: sh
make dotman
Built man pages are now in docs/dist/man directory. If you have
some other custom .cdist directory, e.g. /opt/cdist then use:
.. code-block:: sh
make DOT_CDIST_PATH=/opt/cdist dotman
Note that `dotman`-target has to be built before a `make docs`-run, otherwise
the custom man-pages are not picked up.
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
Installing from source with signature verification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want to install cdist from signed source and verify it, first you need to
download cdist archive and its detached signature.
Get both, *cdist-x.y.z.tar.gz* and *cdist-x.y.z.tar.gz.asc* from release
notes of the desired tag *x.y.z* at
`cdist git repository <https://code.ungleich.ch/ungleich-public/cdist/-/tags>`_.
Get GPG public key used for signing `here <_static/pgp-key-EFD2AE4EC36B6901.asc>`_
and import it into GPG.
Now cdist source archive can be verified using `gpg`, e.g. to verify `cdist-6.2.0`:
.. code-block:: sh
$ gpg --verify cdist-6.2.0.tar.gz.asc cdist-6.2.0.targ.gz
gpg: Signature made Sat Nov 30 23:14:19 2019 CET
gpg: using RSA key 69767822F3ECC3C349C1EFFFEFD2AE4EC36B6901
gpg: Good signature from "ungleich GmbH (ungleich FOSS) <foss@ungleich.ch>" [ultimate]
Further steps are the same as for `installing from git <cdist-install.html#from-git>`_.

47
src/extra/manual/6.3.0/_sources/cdist-integration.rst.txt Normal file
View file

@ -0,0 +1,47 @@
cdist integration / using cdist as library
==========================================
Description
-----------
cdist can be integrate with other applications by importing cdist and other
cdist modules and setting all by hand. There are also helper functions which
aim to ease this integration. Just import **cdist.integration** and use its
functions:
* :strong:`cdist.integration.configure_hosts_simple` for configuration
* :strong:`cdist.integration.install_hosts_simple` for installation.
Functions require `host` and `manifest` parameters.
`host` can be specified as a string representing host or as iterable
of hosts. `manifest` is a path to initial manifest. For other cdist
options default values will be used. `verbose` is a desired verbosity
level which defaults to VERBOSE_INFO. `cdist_path` parameter specifies
path to cdist executable, if it is `None` then functions will try to
find it first from local lib directory and then in PATH.
In case of cdist error :strong:`cdist.Error` exception is raised.
:strong:`WARNING`: cdist integration helper functions are not yet stable!
Examples
--------
.. code-block:: sh
# configure host from python interactive shell
>>> import cdist.integration
>>> cdist.integration.configure_hosts_simple('185.203.114.185',
... '~/.cdist/manifest/init')
# configure host from python interactive shell, specifying verbosity level
>>> import cdist.integration
>>> cdist.integration.configure_hosts_simple(
... '185.203.114.185', '~/.cdist/manifest/init',
... verbose=cdist.argparse.VERBOSE_TRACE)
# configure specified dns hosts from python interactive shell
>>> import cdist.integration
>>> hosts = ('dns1.ungleich.ch', 'dns2.ungleich.ch', 'dns3.ungleich.ch', )
>>> cdist.integration.configure_hosts_simple(hosts,
... '~/.cdist/manifest/init')

211
src/extra/manual/6.3.0/_sources/cdist-inventory.rst.txt Normal file
View file

@ -0,0 +1,211 @@
Inventory
=========
Introduction
------------
cdist comes with simple built-in tag based inventory. It is a simple inventory
with list of hosts and a host has a list of tags.
Inventory functionality is still in **beta** so it can be used only if beta
command line flag is specified (-b, --beta) or setting CDIST_BETA env var.
Description
-----------
The idea is to have simple tagging inventory. There is a list of hosts and for
each host there are tags. Inventory database is a set of files under inventory
database base directory. Filename equals hostname. Each file contains tags for
hostname with each tag on its own line.
Using inventory you can now configure hosts by selecting them by tags.
Tags have no values, as tags are just tags. Tag name-value would in this
context mean that host has two tags and it is selected by specifying that both
tags are present.
This inventory is **KISS** cdist built-in inventory database. You can maintain it
using cdist inventory interface or using standard UNIX tools.
cdist inventory interface
-------------------------
With cdist inventory interface you can list host(s) and tag(s), add host(s),
add tag(s), delete host(s) and delete tag(s).
Configuring hosts using inventory
---------------------------------
config command now has new options, **-t**, **-a** and **-A**.
**-A** means that all hosts in tag db is selected.
**-a** means that selected hosts must contain ALL specified tags.
**-t** means that host specifies tag - all hosts that have specified tags are
selected.
Examples
--------
.. code-block:: sh
# List inventory content
$ cdist inventory list -b
# List inventory for specified host localhost
$ cdist inventory list -b localhost
# List inventory for specified tag loadbalancer
$ cdist inventory list -b -t loadbalancer
# Add hosts to inventory
$ cdist inventory add-host -b web1 web2 web3
# Delete hosts from file old-hosts from inventory
$ cdist inventory del-host -b -f old-hosts
# Add tags to specified hosts
$ cdist inventory add-tag -b -t europe,croatia,web,static web1 web2
# Add tag to all hosts in inventory
$ cdist inventory add-tag -b -t vm
# Delete all tags from specified host
$ cdist inventory del-tag -b -a localhost
# Delete tags read from stdin from hosts specified by file hosts
$ cdist inventory del-tag -b -T - -f hosts
# Configure hosts from inventory with any of specified tags
$ cdist config -b -t web dynamic
# Configure hosts from inventory with all specified tags
$ cdist config -b -t -a web dynamic
# Configure all hosts from inventory db
$ cdist config -b -A
Example of manipulating database
--------------------------------
.. code-block:: sh
$ python3 scripts/cdist inventory list -b
$ python3 scripts/cdist inventory add-host -b localhost
$ python3 scripts/cdist inventory add-host -b test.mycloud.net
$ python3 scripts/cdist inventory list -b
localhost
test.mycloud.net
$ python3 scripts/cdist inventory add-host -b web1.mycloud.net web2.mycloud.net shell1.mycloud.net shell2.mycloud.net
$ python3 scripts/cdist inventory list -b
localhost
test.mycloud.net
web1.mycloud.net
web2.mycloud.net
shell1.mycloud.net
shell2.mycloud.net
$ python3 scripts/cdist inventory add-tag -b -t web web1.mycloud.net web2.mycloud.net
$ python3 scripts/cdist inventory add-tag -b -t shell shell1.mycloud.net shell2.mycloud.net
$ python3 scripts/cdist inventory add-tag -b -t cloud
$ python3 scripts/cdist inventory list -b
localhost cloud
test.mycloud.net cloud
web1.mycloud.net cloud,web
web2.mycloud.net cloud,web
shell1.mycloud.net cloud,shell
shell2.mycloud.net cloud,shell
$ python3 scripts/cdist inventory add-tag -b -t test,web,shell test.mycloud.net
$ python3 scripts/cdist inventory list -b
localhost cloud
test.mycloud.net cloud,shell,test,web
web1.mycloud.net cloud,web
web2.mycloud.net cloud,web
shell1.mycloud.net cloud,shell
shell2.mycloud.net cloud,shell
$ python3 scripts/cdist inventory del-tag -b -t shell test.mycloud.net
$ python3 scripts/cdist inventory list -b
localhost cloud
test.mycloud.net cloud,test,web
web1.mycloud.net cloud,web
web2.mycloud.net cloud,web
shell1.mycloud.net cloud,shell
shell2.mycloud.net cloud,shell
$ python3 scripts/cdist inventory add-tag -b -t all
$ python3 scripts/cdist inventory add-tag -b -t mistake
$ python3 scripts/cdist inventory list -b
localhost all,cloud,mistake
test.mycloud.net all,cloud,mistake,test,web
web1.mycloud.net all,cloud,mistake,web
web2.mycloud.net all,cloud,mistake,web
shell1.mycloud.net all,cloud,mistake,shell
shell2.mycloud.net all,cloud,mistake,shell
$ python3 scripts/cdist inventory del-tag -b -t mistake
$ python3 scripts/cdist inventory list -b
localhost all,cloud
test.mycloud.net all,cloud,test,web
web1.mycloud.net all,cloud,web
web2.mycloud.net all,cloud,web
shell1.mycloud.net all,cloud,shell
shell2.mycloud.net all,cloud,shell
$ python3 scripts/cdist inventory del-host -b localhost
$ python3 scripts/cdist inventory list -b
test.mycloud.net all,cloud,test,web
web1.mycloud.net all,cloud,web
web2.mycloud.net all,cloud,web
shell1.mycloud.net all,cloud,shell
shell2.mycloud.net all,cloud,shell
$ python3 scripts/cdist inventory list -b -t web
test.mycloud.net all,cloud,test,web
web1.mycloud.net all,cloud,web
web2.mycloud.net all,cloud,web
$ python3 scripts/cdist inventory list -b -t -a web test
test.mycloud.net all,cloud,test,web
$ python3 scripts/cdist inventory list -b -t -a web all
test.mycloud.net all,cloud,test,web
web1.mycloud.net all,cloud,web
web2.mycloud.net all,cloud,web
$ python3 scripts/cdist inventory list -b -t web all
test.mycloud.net all,cloud,test,web
web1.mycloud.net all,cloud,web
web2.mycloud.net all,cloud,web
shell1.mycloud.net all,cloud,shell
shell2.mycloud.net all,cloud,shell
$ cd cdist/inventory
$ ls -1
shell1.mycloud.net
shell2.mycloud.net
test.mycloud.net
web1.mycloud.net
web2.mycloud.net
$ ls -l
total 20
-rw-r--r-- 1 darko darko 16 Jun 24 12:43 shell1.mycloud.net
-rw-r--r-- 1 darko darko 16 Jun 24 12:43 shell2.mycloud.net
-rw-r--r-- 1 darko darko 19 Jun 24 12:43 test.mycloud.net
-rw-r--r-- 1 darko darko 14 Jun 24 12:43 web1.mycloud.net
-rw-r--r-- 1 darko darko 14 Jun 24 12:43 web2.mycloud.net
$ cat test.mycloud.net
test
all
web
cloud
$ cat web2.mycloud.net
all
web
cloud
For more info about inventory commands and options see `cdist <man1/cdist.html>`_\ (1).
Using external inventory
------------------------
cdist can be used with any external inventory where external inventory is
some storage or database from which you can get a list of hosts to configure.
cdist can then be fed with this list of hosts through stdin or file using
**-f** option. For example, if your host list is stored in sqlite3 database
hosts.db and you want to select hosts which purpose is **django** then you
can use it with cdist like:
.. code-block:: sh
$ sqlite3 hosts.db "select hostname from hosts where purpose = 'django';" | cdist config

376
src/extra/manual/6.3.0/_sources/cdist-manifest.rst.txt Normal file
View file

@ -0,0 +1,376 @@
Manifest
========
Description
-----------
Manifests are used to define which objects to create.
Objects are instances of **types**, like in object oriented programming languages.
An object is represented by the combination of
**type + slash + object name**: **\__file/etc/cdist-configured** is an
object of the type **__file** with the name **etc/cdist-configured**.
All available types can be found in the **cdist/conf/type/** directory,
use **ls cdist/conf/type** to get the list of available types. If you have
setup the MANPATH correctly, you can use **man cdist-reference** to access
the reference with pointers to the manpages.
Types in manifests are used like normal command line tools. Let's have a look
at an example::
# Create object of type __package with the parameter state = absent
__package apache2 --state absent
# Same with the __directory type
__directory /tmp/cdist --state present
These two lines create objects, which will later be used to realise the
configuration on the target host.
Manifests are executed locally as a shell script using **/bin/sh -e**.
The resulting objects are stored in an internal database.
The same object can be redefined in multiple different manifests as long as
the parameters are exactly the same.
In general, manifests are used to define which types are used depending
on given conditions.
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 <cdist-type.html>`_.
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.
Cdist expects the initial manifest at **cdist/conf/manifest/init**.
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::
__cdistmarker
case "$__target_host" in
localhost)
__directory /home/services/kvm-vm --parents yes
;;
esac
This manifest says: Independent of the host, always use the type
**__cdistmarker**, which creates the file **/etc/cdist-configured**,
with the timestamp as content.
The directory **/home/services/kvm-vm**, including all parent directories,
is only created on the host **localhost**.
As you can see, there is no magic involved, the manifest is simple shell code that
utilises cdist types. Every available type can be executed like a normal
command.
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 <cdist-reference.html>`_).
The following example would include every file with a **.sh** suffix::
# Include *.sh
for manifest in $__manifest/*.sh; do
# And source scripts into our shell environment
. "$manifest"
done
Dependencies
------------
If you want to describe that something requires something else, just
setup the variable "require" to contain the requirements. Multiple
requirements can be added white space separated.
::
1 # No dependency
2 __file /etc/cdist-configured
3
4 # Require above object
5 require="__file/etc/cdist-configured" __link /tmp/cdist-testfile \
6 --source /etc/cdist-configured --type symbolic
7
8 # Require two objects
9 require="__file/etc/cdist-configured __link/tmp/cdist-testfile" \
10 __file /tmp/cdist-another-testfile
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 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
"\__file/etc/cdist-configured" already 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).
If you really need to make all types depend on a common dependency, you can
export the "require" variable as well. But then, if you need to add extra
dependencies to a specific type, you have to make sure that you append these
to the globally already defined one.
::
# First of all, update the package index
__package_update_index
# Upgrade all the installed packages afterwards
require="__package_update_index" __package_upgrade_all
# Create a common dependency for all the next types so that they get to
# be executed only after the package upgrade has finished
export require="__package_upgrade_all"
# Ensure that lighttpd is installed after we have upgraded all the packages
__package lighttpd --state present
# Ensure that munin is installed after lighttpd is present and after all
# the packages are upgraded
require="$require __package/lighttpd" __package munin --state present
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 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>`_.
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.
When cdist sees that this variable is setup, the current created object
automatically depends on the previously created object.
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).
Read also about `notes on CDIST_ORDER_DEPENDENCY <cdist-best-practice.html#notes-on-cdist-order-dependency>`_.
In version 6.2.0 semantic CDIST_ORDER_DEPENDENCY is finally fixed and well defined.
CDIST_ORDER_DEPENDENCY defines type order dependency context. Order dependency context
starts when CDIST_ORDER_DEPENDENCY is set, and ends when it is unset. After each
manifest execution finishes, any existing order dependency context is automatically
unset. This ensures that CDIST_ORDER_DEPENDENCY is valid within the manifest where it
is used. When order dependency context is defined then cdist executes types in the
order in which they are created in the manifest inside order dependency context.
Sometimes the best way to see how something works is to see examples.
Suppose you have defined **initial manifest**:
.. code-block:: sh
__cycle1 cycle1
export CDIST_ORDER_DEPENDENCY=1
__cycle2 cycle2
__cycle3 cycle3
with types **__cycle1**:
.. code-block:: sh
export CDIST_ORDER_DEPENDENCY=1
__file /tmp/cycle11
__file /tmp/cycle12
__file /tmp/cycle13
**__cycle2**:
.. code-block:: sh
__file /tmp/cycle21
export CDIST_ORDER_DEPENDENCY=1
__file /tmp/cycle22
__file /tmp/cycle23
unset CDIST_ORDER_DEPENDENCY
__file /tmp/cycle24
**__cycle3**:
.. code-block:: sh
__file /tmp/cycle31
__file /tmp/cycle32
export CDIST_ORDER_DEPENDENCY=1
__file /tmp/cycle33
__file /tmp/cycle34
For the above config, cdist results in the following expected *dependency graph*
(type *__cycleX* is shown as *cX*, *__file/tmp/cycleXY* is shown as *fcXY*):
::
c1---->fc11
| /\
| |
+----->fc12
| /\
| |
+----->fc13
c2--+--->fc21
/\ |
| |
| +----->fc22
| | /\
| | |
| +----->fc23
| |
| |
| +----->fc24
|
|
c3---->fc31
|
|
+----->fc32
|
|
+----->fc33
| /\
| |
+----->fc34
Before version 6.2.0 the above configuration would result in cycle:
::
ERROR: 185.203.112.26: Cycle detected in object dependencies:
__file/tmp/cycle11 -> __cycle3/cycle3 -> __cycle2/cycle2 -> __cycle1/cycle1 -> __file/tmp/cycle11!
The following manifest shows an example for order dependency contexts:
.. code-block:: sh
__file /tmp/fileA
export CDIST_ORDER_DEPENDENCY=1
__file /tmp/fileB
__file /tmp/fileC
__file /tmp/fileD
unset CDIST_ORDER_DEPENDENCY
__file /tmp/fileE
__file /tmp/fileF
export CDIST_ORDER_DEPENDENCY=1
__file /tmp/fileG
__file /tmp/fileH
unset CDIST_ORDER_DEPENDENCY
__file /tmp/fileI
This means:
* C depends on B
* D depends on C
* H depends on G
and there are no other dependencies from this manifest.
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.
If you wish, you can setup the environment variable CDIST_OVERRIDE
(any value or even empty is ok) to tell cdist, that this object override is
wanted and should be accepted.
ATTENTION: Only use this feature if you are 100% sure in which order
cdist encounters the affected objects, otherwise this results
in an undefined situation.
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
overrides would result in circular dependencies, which is an error.
Examples
--------
The initial manifest may for instance contain the following code:
.. code-block:: sh
# Always create this file, so other sysadmins know cdist is used.
__file /etc/cdist-configured
case "$__target_host" in
my.server.name)
__directory /root/bin/
__file /etc/issue.net --source "$__manifest/issue.net
;;
esac
The manifest of the type "nologin" may look like this:
.. code-block:: sh
__file /etc/nologin --source "$__type/files/default.nologin"
This example makes use of dependencies:
.. code-block:: sh
# Ensure that lighttpd is installed
__package lighttpd --state present
# Ensure that munin makes use of lighttpd instead of the default webserver
# package as decided by the package manager
require="__package/lighttpd" __package munin --state present
How to override objects:
.. code-block:: sh
# for example in the initial manifest
# create user account foobar with some hash for password
__user foobar --password 'some_fancy_hash' --home /home/foobarexample
# ... many statements and includes in the manifest later ...
# somewhere in a conditionally sourced manifest
# (e.g. for example only sourced if a special application is on the target host)
# this leads to an error ...
__user foobar --password 'some_other_hash'
# this tells cdist, that you know that this is an override and should be accepted
CDIST_OVERRIDE=yes __user foobar --password 'some_other_hash'
# it's only an override, means the parameter --home is not touched
# and stays at the original value of /home/foobarexample
Dependencies defined by execution order work as following:
.. code-block:: sh
# Tells cdist to execute all types in the order in which they are created ...
export CDIST_ORDER_DEPENDENCY=on
__sample_type 1
require="__some_type_somewhere/id" __sample_type 2
__example_type 23
# Now this types are executed in the creation order until the variable is unset
unset CDIST_ORDER_DEPENDENCY
# all now following types cdist makes the order ..
__not_in_order_type 42
# how it works :
# this lines above are translated to:
__sample_type 1
require="__some_type_somewhere/id __sample_type/1" __sample_type 2
require="__sample_type/2" __example_type 23
__not_in_order_type 42

94
src/extra/manual/6.3.0/_sources/cdist-messaging.rst.txt Normal file
View file

@ -0,0 +1,94 @@
Messaging
=========
Description
-----------
cdist has a simple but powerful way of allowing communication between
the initial manifest and types as well as types and types.
Whenever execution is passed from cdist to one of the
scripts described below, cdist generate 2 new temporary files
and exports the environment variables **__messages_in** and
**__messages_out** to point to them.
Before handing over the control, the content of the global message
file is copied into the file referenced by **$__messages_in**.
After cdist gained control back, the content of the file referenced
by **$__messages_out** is appended to the global message file.
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 <cdist-manifest.html>`_) and thus you
can only react reliably on messages by objects that you depend on.
Availability
------------
Messaging is possible between all **local** scripts:
- initial manifest
- type/manifest
- type/gencode-local
- type/gencode-remote
Examples
--------
When you want to emit a message use:
.. code-block:: sh
echo "something" >> "$__messages_out"
When you want to react on a message use:
.. code-block:: sh
if grep -q "^__your_type/object/id:something" "$__messages_in"; then
echo "I do something else"
fi
Some real life examples:
.. code-block:: sh
# Reacting on changes from block for keepalive
if grep -q "^__block/keepalive-vrrp" "$__messages_in"; then
echo /etc/init.d/keepalived restart
fi
# Reacting on changes of configuration files
if grep -q "^__file/etc/one" $__messages_in; then
echo 'for init in /etc/init.d/opennebula*; do $init restart; done'
fi
Restart sshd on changes
.. code-block:: sh
os="$(cat "$__global/explorer/os")"
case "$os" in
centos|redhat|suse)
restart="/etc/init.d/sshd restart"
;;
debian|ubuntu)
restart="/etc/init.d/ssh restart"
;;
*)
cat << eof >&2
Unsupported os $os.
If you would like to have this type running on $os,
you can either develop the changes and send a pull
request or ask for a quote at www.ungleich.ch
eof
exit 1
;;
esac
if grep -q "^__key_value/PermitRootLogin" "$__messages_in"; then
echo $restart
fi

19
src/extra/manual/6.3.0/_sources/cdist-os.rst.txt Normal file
View file

@ -0,0 +1,19 @@
Supported operating systems
===========================
cdist was tested or is know to run on at least
* `Alpine Linux <https://alpinelinux.org>`_
* `Archlinux <http://www.archlinux.org>`_
* `CentOS <http://www.centos.org>`_
* `Debian <http://www.debian.org>`_
* `Devuan <https://devuan.org>`_
* `Fedora <http://fedoraproject.org>`_
* `FreeBSD <http://www.freebsd.org>`_
* `Gentoo <http://www.gentoo.org>`_
* `Mac OS X <http://www.apple.com/macosx>`_
* `NetBSD <https://www.netbsd.org>`_
* `OpenBSD <http://www.openbsd.org>`_
* `Redhat <http://www.redhat.com>`_
* `Ubuntu <http://www.ubuntu.com>`_
* `XenServer <http://www.citrix.com/xenserver>`_

73
src/extra/manual/6.3.0/_sources/cdist-parallelization.rst.txt Normal file
View file

@ -0,0 +1,73 @@
Parallelization
===============
Description
-----------
cdist has two modes of parallel operation.
One of them is to operate on each host in separate process. This is enabled
with :strong:`-p/--parallel` option.
The other way is to operate in parallel within one host where you specify
the number of jobs. This is enabled with :strong:`-j/--jobs` option where you
can specify the number of parallel jobs. By default,
:strong:`multiprocessing.cpu_count()` is used. For this mode global explorers,
object preparation and object run are supported.
You can, of course, use those two options together. This means that each host
will be processed by its own process. Within each process cdist will operate
using specified number of parallel jobs.
For more info on those options see :strong:`cdist`\ (1).
Examples
--------
.. code-block:: sh
# Configure hosts read from file hosts.file in parallel
$ cdist config -p -f hosts.file
# Configure hosts read from file hosts.file sequentially but using default
# number of parallel jobs
$ cdist config -j -f hosts.file
# Configure hosts read from file hosts.file in parallel using 16
# parallel jobs
$ cdist config -j 16 -p -f hosts.file
Caveats
-------
When operating in parallel, either by operating in parallel for each host
(-p/--parallel) or by parallel jobs within a host (-j/--jobs), and depending
on target SSH server and its configuration you may encounter connection drops.
This is controlled with sshd :strong:MaxStartups configuration options.
You may also encounter session open refusal. This happens with ssh multiplexing
when you reach maximum number of open sessions permitted per network
connection. In this case ssh will disable multiplexing.
This limit is controlled with sshd :strong:MaxSessions configuration
options. For more details refer to :strong:`sshd_config`\ (5).
For example, if you reach :strong:`MaxSessions` sessions you may get the
following output:
.. code-block:: sh
$ cdist config -b -j 11 -v 78.47.116.244
INFO: cdist: version 4.2.2-55-g640b7f9
INFO: 78.47.116.244: Running global explorers
INFO: 78.47.116.244: Remote transfer in 11 parallel jobs
channel 22: open failed: administratively prohibited: open failed
mux_client_request_session: session request failed: Session open refused by peer
ControlSocket /tmp/tmpuah6fw_t/d886d4b7e4425a102a54bfaff4d2288b/ssh-control-path already exists, disabling multiplexing
INFO: 78.47.116.244: Running global explorers in 11 parallel jobs
channel 22: open failed: administratively prohibited: open failed
mux_client_request_session: session request failed: Session open refused by peer
ControlSocket /tmp/tmpuah6fw_t/d886d4b7e4425a102a54bfaff4d2288b/ssh-control-path already exists, disabling multiplexing
INFO: 78.47.116.244: Running initial manifest /tmp/tmpuah6fw_t/d886d4b7e4425a102a54bfaff4d2288b/data/conf/manifest/init
INFO: 78.47.116.244: Running manifest and explorers for __file/root/host.file
INFO: 78.47.116.244: Generating code for __file/root/host.file
INFO: 78.47.116.244: Finished successful run in 18.655028820037842 seconds
INFO: cdist: Total processing time for 1 host(s): 19.159148693084717

129
src/extra/manual/6.3.0/_sources/cdist-preos.rst.txt Normal file
View file

@ -0,0 +1,129 @@
PreOS
=====
Description
-----------
With cdist you can install and configure new machines. You can use cdist to
create PreOS, minimal OS whose purpose is to boot a new machine.
After PreOS is booted, the machine is ready for installing the desired OS and
afterwards it is ready for configuration.
PreOS creation
--------------
With cdist you can create PreOS.
Currently supported PreOS-es include:
* debian
* ubuntu
* devuan
PreOS is created using the ``cdist preos`` command.
This command has subcommands that determine the desired PreOS.
For example, to create an ubuntu PreOS:
.. code-block:: sh
$ cdist preos ubuntu /preos/preos-ubuntu -B -C \
-k ~/.ssh/id_rsa.pub -p /preos/pxe-ubuntu
For more info about the available options see the cdist manual page.
This will bootstrap (``-B``) ubuntu PreOS in the ``/preos/preos-ubuntu``
directory, it will be configured (``-C``) using default the built-in initial
manifest and with specified ssh authorized key (``-k``).
After bootstrapping and configuration, the PXE boot directory will be
created (``-p``) in ``/preos/pxe-ubuntu``.
After PreOS is created, new machines can be booted using the created PXE
(after proper dhcp and tftp settings).
Since PreOS is configured with ssh authorized key it can be accessed through
ssh, i.e. it can be further installed and configured with cdist.
Implementing a new PreOS sub-command
------------------------------------
preos command is implemented as a plugin system. This plugin system scans for
preos subcommands in the ``cdist/preos/`` distribution directory and also in
``~/.cdist/preos/`` directory if it exists.
preos subcommand is a module or a class that satisfies the following:
* it has the attribute ``_cdist_preos`` set to ``True``
* it defines a function/method ``commandline``.
For a module-based preos subcommand, the ``commandline`` function accepts a
module object as its first argument and the list of command line
arguments (``sys.argv[2:]``).
For a class-based preos subcommand ``commandline`` method should be
static-method and must accept a class as its first argument and the
list of command line arguments (``sys.argv[2:]``).
If preos scanning finds a module/class that has ``_cdist_preos`` set
to ``True`` and a function/method ``commandline`` then this module/class is
registered to preos subcommands. The name of the command is set to ``_preos_name``
attribute if defined in the module/class, defaulting to the module/class name in lowercase.
When a registered preos subcommand is specified, ``commandline``
will be called with the first argument set to module/class and the second
argument set to ``sys.argv[2:]``.
Example of writing new dummy preos sub-command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Module-based preos:
^^^^^^^^^^^^^^^^^^^
#. Create directory ``~/.cdist/preos/`` if it does not exist
#. Create ``~/.cdist/preos/netbsd.py`` with the following contents:
.. code-block:: python
_preos_name = 'netbsd'
_cdist_preos = True
def commandline(cls, args):
print("NetBSD PreOS: {}".format(args))
When you try to run this new preos you will get:
.. code-block:: sh
$ cdist preos -L
Available PreOS-es:
- debian
- devuan
- netbsd
- ubuntu
$ cdist preos netbsd
NetBSD PreOS: []
Class based preos:
^^^^^^^^^^^^^^^^^^
#. Create directory ``~/.cdist/preos/`` if it does not exist
#. Create ``~/.cdist/preos/freebsd.py`` with the following contents:
.. code-block:: python
class FreeBSD(object):
_cdist_preos = True
@classmethod
def commandline(cls, args):
print("FreeBSD dummy preos: {}".format(args))
When you try to run this new preos you will get:
.. code-block:: sh
$ cdist preos -h
Available PreOS-es:
- debian
- devuan
- freebsd
- ubuntu
$ cdist preos freebsd
FreeBSD dummy preos: []
In the ``commandline`` function/method you have all the freedom to actually create
a PreOS.

77
src/extra/manual/6.3.0/_sources/cdist-quickstart.rst.txt Normal file
View file

@ -0,0 +1,77 @@
Quickstart
==========
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.
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**
of the target host to allow root logins: Edit
the file **/etc/ssh/sshd_config** and add one of the following
lines::
# Allow login only via public key
PermitRootLogin without-password
# Allow login via password and public key
PermitRootLogin yes
As cdist uses ssh intensively, it is recommended to setup authentication
with public keys::
# Generate pubkey pair as a normal user
ssh-keygen
# Copy pubkey over to target host
ssh-copy-id root@localhost
Have a look at ssh-agent(1) and ssh-add(1) on how to cache the password for
your public key. Usually it looks like this::
# Start agent and export variables
eval `ssh-agent`
# Add keys (requires password for every identity file)
ssh-add
At this point you should be able to **ssh root@localhost** without
re-entering the password. If something failed until here, ensure that
all steps went successfully and you have read and understood the
documentation.
As soon as you are able to login without password to localhost,
we can use cdist to configure it. You can copy and paste the following
code into your shell to get started and configure localhost::
# Get cdist
git clone git@code.ungleich.ch:ungleich-public/cdist.git
# Create manifest (maps configuration to host(s)
cd cdist
echo '__file /etc/cdist-configured' > cdist/conf/manifest/init
# Configure localhost in verbose mode
./bin/cdist config -v localhost
# Find out that cdist created /etc/cdist-configured
ls -l /etc/cdist-configured
Note: cdist/conf is configuration directory shipped with cdist distribution.
If exists, ~/.cdist, is also automatically used as cdist configuration
directory. So in the above example you could create ~/.cdist directory,
then ~/.cdist/manifest sub-directory and create init manifest
~/.cdist/manifest/init.
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.

573
src/extra/manual/6.3.0/_sources/cdist-real-world.rst.txt Normal file
View file

@ -0,0 +1,573 @@
Dive into real world cdist
==========================
Introduction
------------
This walkthrough shows real world cdist configuration example.
Sample target host is named **test.ungleich.ch**.
Just replace **test.ungleich.ch** with your target hostname.
Our goal is to configure python application hosting. For writing sample
application we will use `Bottle <http://bottlepy.org>`_ WSGI micro web-framework.
It will use PostgreSQL database and it will list items from **items** table.
It will be served by uWSGI server. We will also use the Nginx web server
as a reverse proxy and we want HTTPS.
For HTTPS we will use Let's Encrypt certificate.
For setting up hosting we want to use cdist so we will write a new type
for that. This type will:
- install required packages
- create OS user, user home directory and application home directory
- create PostgreSQL database
- configure uWSGI
- configure Let's Encrypt certificate
- configure nginx.
Our type will not create the actual python application. Its intention is only
to configure hosting for specified user and project. It is up to the user to
create his/her applications.
So let's start.
Creating type layout
--------------------
We will create a new custom type. Let's call it **__sample_bottle_hosting**.
Go to **~/.cdist/type** directory (create it if it does not exist) and create
new type layout::
cd ~/.cdist/type
mkdir __sample_bottle_hosting
cd __sample_bottle_hosting
touch manifest gencode-remote
mkdir parameter
touch parameter/required
Creating __sample_bottle_hosting type parameters
------------------------------------------------
Our type will be configurable through the means of parameters. Let's define
the following parameters:
projectname
name for the project, needed for uWSGI ini file
user
user name
domain
target host domain, needed for Let's Encrypt certificate.
We define parameters to make our type reusable for different projects, user and domain.
Define required parameters::
printf "projectname\n" >> parameter/required
printf "user\n" >> parameter/required
printf "domain\n" >> parameter/required
For details on type parameters see `Defining parameters <cdist-type.html#defining-parameters>`_.
Creating __sample_bottle_hosting type manifest
----------------------------------------------
Next step is to define manifest (~/.cdist/type/__sample_bottle_hosting/manifest).
We also want our type to currently support only Devuan. So we will start by
checking target host OS. We will use `os <cdist-reference.html#explorers>`_
global explorer::
os=$(cat "$__global/explorer/os")
case "$os" in
devuan)
:
;;
*)
echo "OS $os currently not supported" >&2
exit 1
;;
esac
If target host OS is not Devuan then we print error message to stderr
and exit. For other OS-es support we should check and change package names
we should install, because packages differ in different OS-es and in different
OS distributions like GNU/Linux distributions. There can also be a different
configuration locations (e.g. nginx config directory could be in /usr/local tree).
If we detected unsupported OS we should error out. cdist will stop configuration
process and output error message.
Creating user and user directories
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Then we create user and his/her home directory and application home directory.
We will use existing cdist types `__user <man7/cdist-type__user.html>`_ and `__directory <man7/cdist-type__directory.html>`_::
user="$(cat "$__object/parameter/user")"
home="/home/$user"
apphome="$home/app"
# create user
__user "$user" --home "$home" --shell /bin/bash
# create user home dir
require="__user/$user" __directory "$home" \
--owner "$user" --group "$user" --mode 0755
# create app home dir
require="__user/$user __directory/$home" __directory "$apphome" \
--state present --owner "$user" --group "$user" --mode 0755
First we define *user*, *home* and *apphome* variables. User is defined by type's
**user** parameter. Here we use **require** which is cdist's way to define dependencies.
User home directory should be created **after** user is created. And application
home directory is created **after** both user and user home directory are created.
For details on **require** see `Dependencies <cdist-manifest.html#dependencies>`_.
Installing packages
~~~~~~~~~~~~~~~~~~~
Install required packages using existing `__package <man7/cdist-type__package.html>`_ type.
Before installing package we want to update apt package index using
`__apt_update_index <man7/cdist-type__apt_update_index.html>`_::
# define packages that need to be installed
packages_to_install="nginx uwsgi-plugin-python3 python3-dev python3-pip postgresql postgresql-contrib libpq-dev python3-venv uwsgi python3-psycopg2"
# update package index
__apt_update_index
# install packages
for package in $packages_to_install
do require="__apt_update_index" __package $package --state=present
done
Here we use shell for loop. It executes **require="__apt_update_index" __package**
for each member in a list we define in **packages_to_install** variable.
This is much nicer then having as many **require="__apt_update_index" __package**
lines as there are packages we want to install.
For python packages we use `__package_pip <man7/cdist-type__package_pip.html>`_::
# install pip3 packages
for package in bottle bottle-pgsql; do
__package_pip --pip pip3 $package
done
Creating PostgreSQL database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Create PostgreSQL database using `__postgres_database <man7/cdist-type__postgres_database.html>`_
and `__postgres_role <man7/cdist-type__postgres_role.html>`_ for creating database user::
#PostgreSQL db & user
postgres_server=postgresql
# create PostgreSQL db user
require="__package/postgresql" __postgres_role $user --login --createdb
# create PostgreSQL db
require="__postgres_role/$user __package/postgresql" __postgres_database $user \
--owner $user
Configuring uWSGI
~~~~~~~~~~~~~~~~~
Configure uWSGI using `__file <man7/cdist-type__file.html>`_ type::
# configure uWSGI
projectname="$(cat "$__object/parameter/projectname")"
require="__package/uwsgi" __file /etc/uwsgi/apps-enabled/$user.ini \
--owner root --group root --mode 0644 \
--state present \
--source - << EOF
[uwsgi]
socket = $apphome/uwsgi.sock
chdir = $apphome
wsgi-file = $projectname/wsgi.py
touch-reload = $projectname/wsgi.py
processes = 4
threads = 2
chmod-socket = 666
daemonize=true
vacuum = true
uid = $user
gid = $user
EOF
We require package uWSGI present in order to create **/etc/uwsgi/apps-enabled/$user.ini** file.
Installation of uWSGI also creates configuration layout: **/etc/uwsgi/apps-enabled**.
If this directory does not exist then **__file** type would error.
We also use stdin as file content source. For details see `Input from stdin <cdist-type.html#input-from-stdin>`_.
For feading stdin we use here-document (**<<** operator). It allows redirection of subsequent
lines read by the shell to the input of a command until a line containing only the delimiter
and a newline, with no blank characters in between (EOF in our case).
Configuring nginx for Let's Encrypt and HTTPS redirection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Next configure nginx for Let's Encrypt and for HTTP -> HTTPS redirection. For this
purpose we will create new type **__sample_nginx_http_letsencrypt_and_ssl_redirect**
and use it here::
domain="$(cat "$__object/parameter/domain")"
webroot="/var/www/html"
__sample_nginx_http_letsencrypt_and_ssl_redirect "$domain" --webroot "$webroot"
Configuring certificate creation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After HTTP nginx configuration we will create Let's Encrypt certificate using
`__letsencrypt_cert <man7/cdist-type__letsencrypt_cert.html>`_ type.
For Let's Encrypt cert configuration ensure that there is a DNS entry for your
domain. We assure that cert creation is applied after nginx HTTP is configured
for Let's Encrypt to work::
# create SSL cert
require="__package/nginx __sample_nginx_http_letsencrypt_and_ssl_redirect/$domain" \
__letsencrypt_cert --admin-email admin@test.ungleich.ch \
--webroot "$webroot" \
--automatic-renewal \
--renew-hook "service nginx reload" \
--domain "$domain" \
"$domain"
Configuring nginx HTTPS server with uWSGI upstream
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Then we can configure nginx HTTPS server that will use created Let's Encrypt certificate::
# configure nginx
require="__package/nginx __letsencrypt_cert/$domain" \
__file "/etc/nginx/sites-enabled/https-$domain" \
--source - --mode 0644 << EOF
upstream _bottle {
server unix:$apphome/uwsgi.sock;
}
server {
listen 443;
listen [::]:443;
server_name $domain;
access_log /var/log/nginx/access.log;
ssl on;
ssl_certificate /etc/letsencrypt/live/$domain/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/$domain/privkey.pem;
client_max_body_size 256m;
location / {
try_files \$uri @uwsgi;
}
location @uwsgi {
include uwsgi_params;
uwsgi_pass _bottle;
}
}
EOF
Now our manifest is finished.
Complete __sample_bottle_hosting type manifest listing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Here is complete __sample_bottle_hosting type manifest listing,
located in ~/.cdist/type/__sample_bottle_hosting/manifest::
#!/bin/sh
os=$(cat "$__global/explorer/os")
case "$os" in
devuan)
:
;;
*)
echo "OS $os currently not supported" >&2
exit 1
;;
esac
projectname="$(cat "$__object/parameter/projectname")"
user="$(cat "$__object/parameter/user")"
home="/home/$user"
apphome="$home/app"
domain="$(cat "$__object/parameter/domain")"
# create user
__user "$user" --home "$home" --shell /bin/bash
# create user home dir
require="__user/$user" __directory "$home" \
--owner "$user" --group "$user" --mode 0755
# create app home dir
require="__user/$user __directory/$home" __directory "$apphome" \
--state present --owner "$user" --group "$user" --mode 0755
# define packages that need to be installed
packages_to_install="nginx uwsgi-plugin-python3 python3-dev python3-pip postgresql postgresql-contrib libpq-dev python3-venv uwsgi python3-psycopg2"
# update package index
__apt_update_index
# install packages
for package in $packages_to_install
do require="__apt_update_index" __package $package --state=present
done
# install pip3 packages
for package in bottle bottle-pgsql; do
__package_pip --pip pip3 $package
done
#PostgreSQL db & user
postgres_server=postgresql
# create PostgreSQL db user
require="__package/postgresql" __postgres_role $user --login --createdb
# create PostgreSQL db
require="__postgres_role/$user __package/postgresql" __postgres_database $user \
--owner $user
# configure uWSGI
require="__package/uwsgi" __file /etc/uwsgi/apps-enabled/$user.ini \
--owner root --group root --mode 0644 \
--state present \
--source - << EOF
[uwsgi]
socket = $apphome/uwsgi.sock
chdir = $apphome
wsgi-file = $projectname/wsgi.py
touch-reload = $projectname/wsgi.py
processes = 4
threads = 2
chmod-socket = 666
daemonize=true
vacuum = true
uid = $user
gid = $user
EOF
# setup nginx HTTP for Let's Encrypt and SSL redirect
domain="$(cat "$__object/parameter/domain")"
webroot="/var/www/html"
__sample_nginx_http_letsencrypt_and_ssl_redirect "$domain" --webroot "$webroot"
# create SSL cert
require="__package/nginx __sample_nginx_http_letsencrypt_and_ssl_redirect/$domain" \
__letsencrypt_cert --admin-email admin@test.ungleich.ch \
--webroot "$webroot" \
--automatic-renewal \
--renew-hook "service nginx reload" \
--domain "$domain" \
"$domain"
# configure nginx
require="__package/nginx __letsencrypt_cert/$domain" \
__file "/etc/nginx/sites-enabled/https-$domain" \
--source - --mode 0644 << EOF
upstream _bottle {
server unix:$apphome/uwsgi.sock;
}
server {
listen 443;
listen [::]:443;
server_name $domain;
access_log /var/log/nginx/access.log;
ssl on;
ssl_certificate /etc/letsencrypt/live/$domain/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/$domain/privkey.pem;
client_max_body_size 256m;
location / {
try_files \$uri @uwsgi;
}
location @uwsgi {
include uwsgi_params;
uwsgi_pass _bottle;
}
}
EOF
Creating __sample_bottle_hosting type gencode-remote
----------------------------------------------------
Now define **gencode-remote** script: ~/.cdist/type/__sample_bottle_hosting/gencode-remote.
After manifest is applied it should restart uWSGI and nginx services so that our
configuration is active. Our gencode-remote looks like the following::
echo "service uwsgi restart"
echo "service nginx restart"
Our **__sample_bottle_hosting** type is now finished.
Creating __sample_nginx_http_letsencrypt_and_ssl_redirect type
--------------------------------------------------------------
Let's now create **__sample_nginx_http_letsencrypt_and_ssl_redirect** type::
cd ~/.cdist/type
mkdir __sample_nginx_http_letsencrypt_and_ssl_redirect
cd __sample_nginx_http_letsencrypt_and_ssl_redirect
mkdir parameter
echo webroot > parameter/required
touch manifest
touch gencode-remote
Edit manifest::
domain="$__object_id"
webroot="$(cat "$__object/parameter/webroot")"
# make sure we have nginx package
__package nginx
# setup Let's Encrypt HTTP acme challenge, redirect HTTP to HTTPS
require="__package/nginx" __file "/etc/nginx/sites-enabled/http-$domain" \
--source - --mode 0644 << EOF
server {
listen *:80;
listen [::]:80;
server_name $domain;
# Let's Encrypt
location /.well-known/acme-challenge/ {
root $webroot;
}
# Everything else -> SSL
location / {
return 301 https://\$host\$request_uri;
}
}
EOF
Edit gencode-remote::
echo "service nginx reload"
Creating init manifest
----------------------
Next create init manifest::
cd ~/.cdist/manifest
printf "__sample_bottle_hosting --projectname sample --user app --domain \$__target_host sample\n" > sample
Using this init manifest our target host will be configured using our **__sample_bottle_hosting**
type with projectname *sample*, user *app* and domain equal to **__target_host**.
Here the last positional argument *sample* is type's object id. For details on
**__target_host** and **__object_id** see
`Environment variables (for reading) <cdist-reference.html#environment-variables-for-reading>`_
reference.
Configuring host
----------------
Finally configure test.ungleich.ch::
cdist config -v -i ~/.cdist/manifest/sample test.ungleich.ch
After cdist configuration is successfully finished our host is ready.
Creating python bottle application
----------------------------------
We now need to create Bottle application. As you remember from the beginning
of this walkthrough our type does not create the actual python application,
its intention is only to configure hosting for specified user and project.
It is up to the user to create his/her applications.
Become app user::
su -l app
Preparing database
~~~~~~~~~~~~~~~~~~
We need to prepare database for our application. Create table and
insert some items::
psql -c "create table items (item varchar(255));"
psql -c "insert into items(item) values('spam');"
psql -c "insert into items(item) values('eggs');"
psql -c "insert into items(item) values('sausage');"
Creating application
~~~~~~~~~~~~~~~~~~~~
Next create sample app::
cd /home/app/app
mkdir sample
cd sample
Create app.py with the following content::
#!/usr/bin/env python3
import bottle
import bottle_pgsql
app = application = bottle.Bottle()
plugin = bottle_pgsql.Plugin('dbname=app user=app password=')
app.install(plugin)
@app.route('/')
def show_index(db):
db.execute('select * from items')
items = db.fetchall() or []
rv = '<html><body><h3>Items:</h3><ul>'
for item in items:
rv += '<li>' + str(item['item']) + '</li>'
rv += '</ul></body></html>'
return rv
if __name__ == '__main__':
bottle.run(app=app, host='0.0.0.0', port=8080)
Create wsgi.py with the following content::
import os
os.chdir(os.path.dirname(__file__))
import app
application = app.app
We have configured uWSGI with **touch-reload = $projectname/wsgi.py** so after
we have changed our **wsgi.py** file uWSGI reloads the application.
Our application selects and lists items from **items** table.
Openning application
~~~~~~~~~~~~~~~~~~~~
Finally try the application::
http://test.ungleich.ch/
It should redirect to HTTPS and return:
.. container:: highlight
.. raw:: html
<h3>Items:</h3>
<ul>
<li>spam</li>
<li>eggs</li>
<li>sausage</li>
</ul>
What's next?
------------
Continue reading next sections ;)

460
src/extra/manual/6.3.0/_sources/cdist-reference.rst.txt Normal file
View file

@ -0,0 +1,460 @@
Reference
=========
Variable, path and type reference for cdist
Explorers
---------
The following global explorers are available:
- cpu_cores
- cpu_sockets
- disks
- hostname
- init
- interfaces
- is-freebsd-jail
- kernel_name
- lsb_codename
- lsb_description
- lsb_id
- lsb_release
- machine
- machine_type
- memory
- os
- os_release
- os_version
- runlevel
Paths
-----
$HOME/.cdist
The standard cdist configuration directory relative to your home directory.
This is usually the place you want to store your site specific configuration.
cdist/conf/
The distribution configuration directory.
This contains types and explorers to be used.
cdist/inventory/
The distribution inventory directory.
This path is relative to cdist installation directory.
cdist/preos/
The distribution PreOS plugins directory.
confdir
Cdist will use all available configuration directories and create
a temporary confdir containing links to the real configuration directories.
This way it is possible to merge configuration directories.
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
values from the explorers to decide which configuration to create
for the specified target host.
Its intent is to used to define mapping from configurations to hosts.
confdir/manifest/*
All other files in this directory are not directly used by cdist, but you
can separate configuration mappings, if you have a lot of code in the
conf/manifest/init file. This may also be helpful to have different admins
maintain different groups of hosts.
confdir/explorer/<name>
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 <cdist-type.html>`_.
confdir/type/<name>/
Home of the type <name>.
This directory is referenced by the variable __type (see below).
confdir/type/<name>/man.rst
Manpage in reStructuredText format (required for inclusion into upstream).
confdir/type/<name>/manifest
Used to generate additional objects from a type.
confdir/type/<name>/gencode-local
Used to generate code to be executed on the source host.
confdir/type/<name>/gencode-remote
Used to generate code to be executed on the target host.
confdir/type/<name>/parameter/required
Parameters required by type, \n separated list.
confdir/type/<name>/parameter/optional
Parameters optionally accepted by type, \n separated list.
confdir/type/<name>/parameter/default/*
Default values for optional parameters.
Assuming an optional parameter name of 'foo', it's default value would
be read from the file confdir/type/<name>/parameter/default/foo.
confdir/type/<name>/parameter/boolean
Boolean parameters accepted by type, \n separated list.
confdir/type/<name>/explorer
Location of the type specific explorers.
This directory is referenced by the variable __type_explorer (see below).
See `cdist explorer <cdist-explorer.html>`_.
confdir/type/<name>/files
This directory is reserved for user data and will not be used
by cdist at any time. It can be used for storing supplementary
files (like scripts to act as a template or configuration files).
out/
This directory contains output of cdist and is usually located
in a temporary directory and thus will be removed after the run.
This directory is referenced by the variable __global (see below).
out/explorer
Output of general explorers.
out/object
Objects created for the host.
out/object/<object>
Contains all object specific information.
This directory is referenced by the variable __object (see below).
out/object/<object>/explorers
Output of type specific explorers, per object.
Types
-----
The following types are available:
- __acl (`cdist-type__acl(7) <man7/cdist-type__acl.html>`_)
- __apt_default_release (`cdist-type__apt_default_release(7) <man7/cdist-type__apt_default_release.html>`_)
- __apt_key (`cdist-type__apt_key(7) <man7/cdist-type__apt_key.html>`_)
- __apt_key_uri (`cdist-type__apt_key_uri(7) <man7/cdist-type__apt_key_uri.html>`_)
- __apt_mark (`cdist-type__apt_mark(7) <man7/cdist-type__apt_mark.html>`_)
- __apt_norecommends (`cdist-type__apt_norecommends(7) <man7/cdist-type__apt_norecommends.html>`_)
- __apt_ppa (`cdist-type__apt_ppa(7) <man7/cdist-type__apt_ppa.html>`_)
- __apt_source (`cdist-type__apt_source(7) <man7/cdist-type__apt_source.html>`_)
- __apt_update_index (`cdist-type__apt_update_index(7) <man7/cdist-type__apt_update_index.html>`_)
- __block (`cdist-type__block(7) <man7/cdist-type__block.html>`_)
- __ccollect_source (`cdist-type__ccollect_source(7) <man7/cdist-type__ccollect_source.html>`_)
- __cdist (`cdist-type__cdist(7) <man7/cdist-type__cdist.html>`_)
- __cdistmarker (`cdist-type__cdistmarker(7) <man7/cdist-type__cdistmarker.html>`_)
- __check_messages (`cdist-type__check_messages(7) <man7/cdist-type__check_messages.html>`_)
- __chroot_mount (`cdist-type__chroot_mount(7) <man7/cdist-type__chroot_mount.html>`_)
- __chroot_umount (`cdist-type__chroot_umount(7) <man7/cdist-type__chroot_umount.html>`_)
- __clean_path (`cdist-type__clean_path(7) <man7/cdist-type__clean_path.html>`_)
- __config_file (`cdist-type__config_file(7) <man7/cdist-type__config_file.html>`_)
- __consul (`cdist-type__consul(7) <man7/cdist-type__consul.html>`_)
- __consul_agent (`cdist-type__consul_agent(7) <man7/cdist-type__consul_agent.html>`_)
- __consul_check (`cdist-type__consul_check(7) <man7/cdist-type__consul_check.html>`_)
- __consul_reload (`cdist-type__consul_reload(7) <man7/cdist-type__consul_reload.html>`_)
- __consul_service (`cdist-type__consul_service(7) <man7/cdist-type__consul_service.html>`_)
- __consul_template (`cdist-type__consul_template(7) <man7/cdist-type__consul_template.html>`_)
- __consul_template_template (`cdist-type__consul_template_template(7) <man7/cdist-type__consul_template_template.html>`_)
- __consul_watch_checks (`cdist-type__consul_watch_checks(7) <man7/cdist-type__consul_watch_checks.html>`_)
- __consul_watch_event (`cdist-type__consul_watch_event(7) <man7/cdist-type__consul_watch_event.html>`_)
- __consul_watch_key (`cdist-type__consul_watch_key(7) <man7/cdist-type__consul_watch_key.html>`_)
- __consul_watch_keyprefix (`cdist-type__consul_watch_keyprefix(7) <man7/cdist-type__consul_watch_keyprefix.html>`_)
- __consul_watch_nodes (`cdist-type__consul_watch_nodes(7) <man7/cdist-type__consul_watch_nodes.html>`_)
- __consul_watch_service (`cdist-type__consul_watch_service(7) <man7/cdist-type__consul_watch_service.html>`_)
- __consul_watch_services (`cdist-type__consul_watch_services(7) <man7/cdist-type__consul_watch_services.html>`_)
- __cron (`cdist-type__cron(7) <man7/cdist-type__cron.html>`_)
- __daemontools (`cdist-type__daemontools(7) <man7/cdist-type__daemontools.html>`_)
- __daemontools_service (`cdist-type__daemontools_service(7) <man7/cdist-type__daemontools_service.html>`_)
- __debconf_set_selections (`cdist-type__debconf_set_selections(7) <man7/cdist-type__debconf_set_selections.html>`_)
- __directory (`cdist-type__directory(7) <man7/cdist-type__directory.html>`_)
- __docker (`cdist-type__docker(7) <man7/cdist-type__docker.html>`_)
- __docker_compose (`cdist-type__docker_compose(7) <man7/cdist-type__docker_compose.html>`_)
- __docker_config (`cdist-type__docker_config(7) <man7/cdist-type__docker_config.html>`_)
- __docker_secret (`cdist-type__docker_secret(7) <man7/cdist-type__docker_secret.html>`_)
- __docker_stack (`cdist-type__docker_stack(7) <man7/cdist-type__docker_stack.html>`_)
- __docker_swarm (`cdist-type__docker_swarm(7) <man7/cdist-type__docker_swarm.html>`_)
- __dog_vdi (`cdist-type__dog_vdi(7) <man7/cdist-type__dog_vdi.html>`_)
- __dot_file (`cdist-type__dot_file(7) <man7/cdist-type__dot_file.html>`_)
- __file (`cdist-type__file(7) <man7/cdist-type__file.html>`_)
- __filesystem (`cdist-type__filesystem(7) <man7/cdist-type__filesystem.html>`_)
- __firewalld_rule (`cdist-type__firewalld_rule(7) <man7/cdist-type__firewalld_rule.html>`_)
- __firewalld_start (`cdist-type__firewalld_start(7) <man7/cdist-type__firewalld_start.html>`_)
- __git (`cdist-type__git(7) <man7/cdist-type__git.html>`_)
- __go_get (`cdist-type__go_get(7) <man7/cdist-type__go_get.html>`_)
- __golang_from_vendor (`cdist-type__golang_from_vendor(7) <man7/cdist-type__golang_from_vendor.html>`_)
- __grafana_dashboard (`cdist-type__grafana_dashboard(7) <man7/cdist-type__grafana_dashboard.html>`_)
- __group (`cdist-type__group(7) <man7/cdist-type__group.html>`_)
- __hostname (`cdist-type__hostname(7) <man7/cdist-type__hostname.html>`_)
- __hosts (`cdist-type__hosts(7) <man7/cdist-type__hosts.html>`_)
- __install_bootloader_grub (`cdist-type__install_bootloader_grub(7) <man7/cdist-type__install_bootloader_grub.html>`_)
- __install_chroot_mount (`cdist-type__install_chroot_mount(7) <man7/cdist-type__install_chroot_mount.html>`_)
- __install_chroot_umount (`cdist-type__install_chroot_umount(7) <man7/cdist-type__install_chroot_umount.html>`_)
- __install_config (`cdist-type__install_config(7) <man7/cdist-type__install_config.html>`_)
- __install_coreos (`cdist-type__install_coreos(7) <man7/cdist-type__install_coreos.html>`_)
- __install_directory (`cdist-type__install_directory(7) <man7/cdist-type__install_directory.html>`_)
- __install_file (`cdist-type__install_file(7) <man7/cdist-type__install_file.html>`_)
- __install_fstab (`cdist-type__install_fstab(7) <man7/cdist-type__install_fstab.html>`_)
- __install_generate_fstab (`cdist-type__install_generate_fstab(7) <man7/cdist-type__install_generate_fstab.html>`_)
- __install_mkfs (`cdist-type__install_mkfs(7) <man7/cdist-type__install_mkfs.html>`_)
- __install_mount (`cdist-type__install_mount(7) <man7/cdist-type__install_mount.html>`_)
- __install_partition_msdos (`cdist-type__install_partition_msdos(7) <man7/cdist-type__install_partition_msdos.html>`_)
- __install_partition_msdos_apply (`cdist-type__install_partition_msdos_apply(7) <man7/cdist-type__install_partition_msdos_apply.html>`_)
- __install_reboot (`cdist-type__install_reboot(7) <man7/cdist-type__install_reboot.html>`_)
- __install_reset_disk (`cdist-type__install_reset_disk(7) <man7/cdist-type__install_reset_disk.html>`_)
- __install_stage (`cdist-type__install_stage(7) <man7/cdist-type__install_stage.html>`_)
- __install_umount (`cdist-type__install_umount(7) <man7/cdist-type__install_umount.html>`_)
- __iptables_apply (`cdist-type__iptables_apply(7) <man7/cdist-type__iptables_apply.html>`_)
- __iptables_rule (`cdist-type__iptables_rule(7) <man7/cdist-type__iptables_rule.html>`_)
- __issue (`cdist-type__issue(7) <man7/cdist-type__issue.html>`_)
- __jail (`cdist-type__jail(7) <man7/cdist-type__jail.html>`_)
- __jail_freebsd10 (`cdist-type__jail_freebsd10(7) <man7/cdist-type__jail_freebsd10.html>`_)
- __jail_freebsd9 (`cdist-type__jail_freebsd9(7) <man7/cdist-type__jail_freebsd9.html>`_)
- __key_value (`cdist-type__key_value(7) <man7/cdist-type__key_value.html>`_)
- __keyboard (`cdist-type__keyboard(7) <man7/cdist-type__keyboard.html>`_)
- __letsencrypt_cert (`cdist-type__letsencrypt_cert(7) <man7/cdist-type__letsencrypt_cert.html>`_)
- __line (`cdist-type__line(7) <man7/cdist-type__line.html>`_)
- __link (`cdist-type__link(7) <man7/cdist-type__link.html>`_)
- __locale (`cdist-type__locale(7) <man7/cdist-type__locale.html>`_)
- __locale_system (`cdist-type__locale_system(7) <man7/cdist-type__locale_system.html>`_)
- __motd (`cdist-type__motd(7) <man7/cdist-type__motd.html>`_)
- __mount (`cdist-type__mount(7) <man7/cdist-type__mount.html>`_)
- __mysql_database (`cdist-type__mysql_database(7) <man7/cdist-type__mysql_database.html>`_)
- __openldap_server (`cdist-type__openldap_server(7) <man7/cdist-type__openldap_server.html>`_)
- __package (`cdist-type__package(7) <man7/cdist-type__package.html>`_)
- __package_apk (`cdist-type__package_apk(7) <man7/cdist-type__package_apk.html>`_)
- __package_apt (`cdist-type__package_apt(7) <man7/cdist-type__package_apt.html>`_)
- __package_dpkg (`cdist-type__package_dpkg(7) <man7/cdist-type__package_dpkg.html>`_)
- __package_emerge (`cdist-type__package_emerge(7) <man7/cdist-type__package_emerge.html>`_)
- __package_emerge_dependencies (`cdist-type__package_emerge_dependencies(7) <man7/cdist-type__package_emerge_dependencies.html>`_)
- __package_luarocks (`cdist-type__package_luarocks(7) <man7/cdist-type__package_luarocks.html>`_)
- __package_opkg (`cdist-type__package_opkg(7) <man7/cdist-type__package_opkg.html>`_)
- __package_pacman (`cdist-type__package_pacman(7) <man7/cdist-type__package_pacman.html>`_)
- __package_pip (`cdist-type__package_pip(7) <man7/cdist-type__package_pip.html>`_)
- __package_pkg_freebsd (`cdist-type__package_pkg_freebsd(7) <man7/cdist-type__package_pkg_freebsd.html>`_)
- __package_pkg_openbsd (`cdist-type__package_pkg_openbsd(7) <man7/cdist-type__package_pkg_openbsd.html>`_)
- __package_pkgng_freebsd (`cdist-type__package_pkgng_freebsd(7) <man7/cdist-type__package_pkgng_freebsd.html>`_)
- __package_rubygem (`cdist-type__package_rubygem(7) <man7/cdist-type__package_rubygem.html>`_)
- __package_update_index (`cdist-type__package_update_index(7) <man7/cdist-type__package_update_index.html>`_)
- __package_upgrade_all (`cdist-type__package_upgrade_all(7) <man7/cdist-type__package_upgrade_all.html>`_)
- __package_yum (`cdist-type__package_yum(7) <man7/cdist-type__package_yum.html>`_)
- __package_zypper (`cdist-type__package_zypper(7) <man7/cdist-type__package_zypper.html>`_)
- __pacman_conf (`cdist-type__pacman_conf(7) <man7/cdist-type__pacman_conf.html>`_)
- __pacman_conf_integrate (`cdist-type__pacman_conf_integrate(7) <man7/cdist-type__pacman_conf_integrate.html>`_)
- __pf_apply (`cdist-type__pf_apply(7) <man7/cdist-type__pf_apply.html>`_)
- __pf_ruleset (`cdist-type__pf_ruleset(7) <man7/cdist-type__pf_ruleset.html>`_)
- __ping (`cdist-type__ping(7) <man7/cdist-type__ping.html>`_)
- __postfix (`cdist-type__postfix(7) <man7/cdist-type__postfix.html>`_)
- __postfix_master (`cdist-type__postfix_master(7) <man7/cdist-type__postfix_master.html>`_)
- __postfix_postconf (`cdist-type__postfix_postconf(7) <man7/cdist-type__postfix_postconf.html>`_)
- __postfix_postmap (`cdist-type__postfix_postmap(7) <man7/cdist-type__postfix_postmap.html>`_)
- __postfix_reload (`cdist-type__postfix_reload(7) <man7/cdist-type__postfix_reload.html>`_)
- __postgres_database (`cdist-type__postgres_database(7) <man7/cdist-type__postgres_database.html>`_)
- __postgres_extension (`cdist-type__postgres_extension(7) <man7/cdist-type__postgres_extension.html>`_)
- __postgres_role (`cdist-type__postgres_role(7) <man7/cdist-type__postgres_role.html>`_)
- __process (`cdist-type__process(7) <man7/cdist-type__process.html>`_)
- __prometheus_alertmanager (`cdist-type__prometheus_alertmanager(7) <man7/cdist-type__prometheus_alertmanager.html>`_)
- __prometheus_exporter (`cdist-type__prometheus_exporter(7) <man7/cdist-type__prometheus_exporter.html>`_)
- __prometheus_server (`cdist-type__prometheus_server(7) <man7/cdist-type__prometheus_server.html>`_)
- __pyvenv (`cdist-type__pyvenv(7) <man7/cdist-type__pyvenv.html>`_)
- __qemu_img (`cdist-type__qemu_img(7) <man7/cdist-type__qemu_img.html>`_)
- __rbenv (`cdist-type__rbenv(7) <man7/cdist-type__rbenv.html>`_)
- __rsync (`cdist-type__rsync(7) <man7/cdist-type__rsync.html>`_)
- __rvm (`cdist-type__rvm(7) <man7/cdist-type__rvm.html>`_)
- __rvm_gem (`cdist-type__rvm_gem(7) <man7/cdist-type__rvm_gem.html>`_)
- __rvm_gemset (`cdist-type__rvm_gemset(7) <man7/cdist-type__rvm_gemset.html>`_)
- __rvm_ruby (`cdist-type__rvm_ruby(7) <man7/cdist-type__rvm_ruby.html>`_)
- __sensible_editor (`cdist-type__sensible_editor(7) <man7/cdist-type__sensible_editor.html>`_)
- __ssh_authorized_key (`cdist-type__ssh_authorized_key(7) <man7/cdist-type__ssh_authorized_key.html>`_)
- __ssh_authorized_keys (`cdist-type__ssh_authorized_keys(7) <man7/cdist-type__ssh_authorized_keys.html>`_)
- __ssh_dot_ssh (`cdist-type__ssh_dot_ssh(7) <man7/cdist-type__ssh_dot_ssh.html>`_)
- __staged_file (`cdist-type__staged_file(7) <man7/cdist-type__staged_file.html>`_)
- __start_on_boot (`cdist-type__start_on_boot(7) <man7/cdist-type__start_on_boot.html>`_)
- __sysctl (`cdist-type__sysctl(7) <man7/cdist-type__sysctl.html>`_)
- __systemd_unit (`cdist-type__systemd_unit(7) <man7/cdist-type__systemd_unit.html>`_)
- __timezone (`cdist-type__timezone(7) <man7/cdist-type__timezone.html>`_)
- __ufw (`cdist-type__ufw(7) <man7/cdist-type__ufw.html>`_)
- __ufw_rule (`cdist-type__ufw_rule(7) <man7/cdist-type__ufw_rule.html>`_)
- __update_alternatives (`cdist-type__update_alternatives(7) <man7/cdist-type__update_alternatives.html>`_)
- __user (`cdist-type__user(7) <man7/cdist-type__user.html>`_)
- __user_groups (`cdist-type__user_groups(7) <man7/cdist-type__user_groups.html>`_)
- __xymon_apache (`cdist-type__xymon_apache(7) <man7/cdist-type__xymon_apache.html>`_)
- __xymon_client (`cdist-type__xymon_client(7) <man7/cdist-type__xymon_client.html>`_)
- __xymon_config (`cdist-type__xymon_config(7) <man7/cdist-type__xymon_config.html>`_)
- __xymon_server (`cdist-type__xymon_server(7) <man7/cdist-type__xymon_server.html>`_)
- __yum_repo (`cdist-type__yum_repo(7) <man7/cdist-type__yum_repo.html>`_)
- __zypper_repo (`cdist-type__zypper_repo(7) <man7/cdist-type__zypper_repo.html>`_)
- __zypper_service (`cdist-type__zypper_service(7) <man7/cdist-type__zypper_service.html>`_)
Objects
-------
For object to object communication and tests, the following paths are
usable within a object directory:
files
This directory is reserved for user data and will not be used
by cdist at any time. It can be used freely by the type
(for instance to store template results).
changed
This empty file exists in an object directory, if the object has
code to be executed (either remote or local).
stdin
This file exists and contains data, if data was provided on stdin
when the type was called.
Environment variables (for reading)
-----------------------------------
The following environment variables are exported by cdist:
__cdist_log_level, __cdist_log_level_name
cdist log level value and cdist log level name. One of:
+----------------+-----------------+
| Log level name | Log level value |
+================+=================+
| OFF | 60 |
+----------------+-----------------+
| ERROR | 40 |
+----------------+-----------------+
| WARNING | 30 |
+----------------+-----------------+
| INFO | 20 |
+----------------+-----------------+
| VERBOSE | 15 |
+----------------+-----------------+
| DEBUG | 10 |
+----------------+-----------------+
| TRACE | 5 |
+----------------+-----------------+
Available for: initial manifest, explorer, type manifest, type explorer,
type gencode.
__cdist_dry_run
Is set only when doing dry run (-n flag).
Available for: initial manifest, explorer, type manifest, type explorer,
type gencode.
__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.
__global
Directory that contains generic output like explorer.
Available for: initial manifest, type manifest, type gencode, shell.
__messages_in
File to read messages from.
Available for: initial manifest, type manifest, type gencode.
__messages_out
File to write messages.
Available for: initial manifest, type manifest, type gencode.
__object
Directory that contains the current object.
Available for: type manifest, type explorer, type gencode and code scripts.
__object_id
The type unique object id.
Available for: type manifest, type explorer, type gencode and code scripts.
Note: The leading and the trailing "/" will always be stripped (caused by
the filesystem database and ensured by the core).
Note: Double slashes ("//") will not be fixed and result in an error.
__object_name
The full qualified name of the current object.
Available for: type manifest, type explorer, type gencode.
__target_host
The host we are deploying to. This is primary variable. It's content is
literally the one user passed in.
Available for: explorer, initial manifest, type explorer, type manifest, type gencode, shell.
__target_hostname
The hostname of host we are deploying to. This variable is derived from
**__target_host** (using **socket.getaddrinfo(__target_host)** and then
**socket.gethostbyaddr()**).
Available for: explorer, initial manifest, type explorer, type manifest, type gencode, shell.
__target_fqdn
The fully qualified domain name of the host we are deploying to.
This variable is derived from **__target_host**
(using **socket.getfqdn()**).
Available for: explorer, initial manifest, type explorer, type manifest, type gencode, shell.
__target_host_tags
Comma separated list of target host tags.
Available for: explorer, initial manifest, type explorer, type manifest, type gencode, shell.
__type
Path to the current type.
Available for: type manifest, type gencode.
__type_explorer
Directory that contains the type explorers.
Available for: type explorer.
Environment variables (for writing)
-----------------------------------
The following environment variables influence the behaviour of cdist:
require
Setup dependencies between objects (see `cdist manifest <cdist-manifest.html>`_).
__cdist_log_level
cdist log level value. One of:
+----------------+-----------------+
| Log level | Log level value |
+================+=================+
| OFF | 60 |
+----------------+-----------------+
| ERROR | 40 |
+----------------+-----------------+
| WARNING | 30 |
+----------------+-----------------+
| INFO | 20 |
+----------------+-----------------+
| VERBOSE | 15 |
+----------------+-----------------+
| DEBUG | 10 |
+----------------+-----------------+
| TRACE | 5 |
+----------------+-----------------+
If set cdist will set this log level in
accordance with configuration rules. If cdist invokation is used
in types then nested cdist will honor this specified log level if
not specified otherwise while invoking it.
CDIST_PATH
Colon delimited list of config directories.
CDIST_LOCAL_SHELL
Use this shell locally instead of /bin/sh to execute scripts.
CDIST_REMOTE_SHELL
Use this shell remotely instead of /bin/sh to execute scripts.
CDIST_OVERRIDE
Allow overwriting type parameters (see `cdist manifest <cdist-manifest.html>`_).
CDIST_ORDER_DEPENDENCY
Create dependencies based on the execution order (see `cdist manifest <cdist-manifest.html>`_).
Note that in version 6.2.0 semantic of this processing mode is finally fixed and well defined.
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).
CDIST_INVENTORY_DIR
Use this directory as inventory directory.
CDIST_BETA
Enable beta functionalities.
CDIST_CACHE_PATH_PATTERN
Custom cache path pattern.

28
src/extra/manual/6.3.0/_sources/cdist-remote-exec-copy.rst.txt Normal file
View file

@ -0,0 +1,28 @@
Remote exec and copy commands
=============================
Cdist interacts with the target host in two ways:
- it executes code (__remote_exec)
- and it copies files (__remote_copy)
By default this is accomplished with ssh and scp respectively.
The default implementations used by cdist are::
__remote_exec: ssh -o User=root
__remote_copy: scp -o User=root
The user can override these defaults by providing custom implementations and
passing them to cdist with the --remote-exec and/or --remote-copy arguments.
For __remote_exec, the custom implementation must behave as if it where ssh.
For __remote_copy, it must behave like scp.
Please notice, custom implementations should work like ssh/scp so __remote_copy
must support IPv6 addresses enclosed in square brackets. For __remote_exec you
must take into account that for some options (like -L) IPv6 addresses can be
specified by enclosed in square brackets (see :strong:`ssh`\ (1) and
:strong:`scp`\ (1)).
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.

88
src/extra/manual/6.3.0/_sources/cdist-saving-output-streams.rst.txt Normal file
View file

@ -0,0 +1,88 @@
Saving output streams
=====================
Description
-----------
Since version 4.8.0 cdist, by default, saves output streams to local cache.
Saving output streams is implemented because important information was lost
during a config run, hidden in all other output.
Now all created output is bound to the context where it was produced.
Saving output streams include stdout and stderr of init manifest, remote
commands and for each object stdout and stderr of manifest, gencode-\* and code-\*.
Output stream files are created only if some output is produced. For more info
on these cache files see `Local cache overview <cdist-cache.html>`_.
Also, in case of an error, cdist can now exit and show all information it has
about the error.
For example:
.. code-block:: sh
$ ./bin/cdist config -v -i ~/.cdist/manifest/init-output-streams $(cat ~/ungleich/data/opennebula-debian9-test )
INFO: 185.203.112.42: Starting configuration run
INFO: 185.203.112.42: Processing __myline/test
ERROR: 185.203.112.42: Command failed: '/bin/sh -e /tmp/tmpow6cwemh/75ee6a79e32da093da23fe4a13dd104b/data/object/__myline/test/.cdist-kisrqlpw/code-local'
return code: 1
---- BEGIN stdout ----
---- END stdout ----
Error processing object '__myline/test'
========================================
name: __myline/test
path: /tmp/tmpow6cwemh/75ee6a79e32da093da23fe4a13dd104b/data/object/__myline/test/.cdist-kisrqlpw
source: /home/darko/.cdist/manifest/init-output-streams
type: /tmp/tmpow6cwemh/75ee6a79e32da093da23fe4a13dd104b/data/conf/type/__myline
---- BEGIN manifest:stderr ----
myline manifest stderr
---- END manifest:stderr ----
---- BEGIN gencode-remote:stderr ----
test gencode-remote error
---- END gencode-remote:stderr ----
---- BEGIN code-local:stderr ----
error
---- END code-local:stderr ----
ERROR: cdist: Failed to configure the following hosts: 185.203.112.42
Upon successful run execution state is saved to local cache and temporary
directory is removed.
In case of an error temporary directory is not removed and can be further
discovered.
There is also an option :strong:`-S/--disable-saving-output-streams` for
disabling saving output streams. In this case error reporting can look
like this:
.. code-block:: sh
$ ./bin/cdist config -v -S -i ~/.cdist/manifest/init-output-streams $(cat ~/ungleich/data/opennebula-debian9-test )
INFO: 185.203.112.42: Starting configuration run
test stdout output streams
test stderr output streams
myline manifest stdout
myline manifest stderr
test gencode-remote error
INFO: 185.203.112.42: Processing __myline/test
error
ERROR: 185.203.112.42: Command failed: '/bin/sh -e /tmp/tmpzomy0wis/75ee6a79e32da093da23fe4a13dd104b/data/object/__myline/test/.cdist-n566pqut/code-local'
return code: 1
---- BEGIN stdout ----
---- END stdout ----
Error processing object '__myline/test'
========================================
name: __myline/test
path: /tmp/tmpzomy0wis/75ee6a79e32da093da23fe4a13dd104b/data/object/__myline/test/.cdist-n566pqut
source: /home/darko/.cdist/manifest/init-output-streams
type: /tmp/tmpzomy0wis/75ee6a79e32da093da23fe4a13dd104b/data/conf/type/__myline
ERROR: cdist: Failed to configure the following hosts: 185.203.112.42

70
src/extra/manual/6.3.0/_sources/cdist-stages.rst.txt Normal file
View file

@ -0,0 +1,70 @@
Execution stages
================
Description
-----------
When cdist is started, it passes through different stages.
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
explorers are copied back into the local cache. The results can be used by
manifests and types.
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
the objects as defined in the manifest for the specific host. In this stage,
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
-------------------------------------
Every object is checked whether its type has explorers and if so, these are
executed on the target host. The results are transferred back
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
--------------------------------
Every object is checked whether its type has a executable manifest. The
manifest script may generate and change the created objects. In other words,
one type can reuse other types.
For instance the object __apache/www.example.org is of type __apache, which may
contain a manifest script, which creates new objects of type __file.
The newly created objects are merged back into the existing tree. No conflicts
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
------------------------
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
target on stdout. If the gencode executables fail, they must print diagnostic
messages on stderr and exit non-zero.
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
--------------
The cache stores the information from the current run for later use.
Summary
-------
If, and only if, all the stages complete without errors, the configuration
will be applied to the target.

26
src/extra/manual/6.3.0/_sources/cdist-support.rst.txt Normal file
View file

@ -0,0 +1,26 @@
Support
-------
Chat
~~~~
Chat with us: `ungleich chat <https://chat.ungleich.ch/ungleich/channels/cdist>`_.
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
`ungleich <http://www.ungleich.ch/>`_.

64
src/extra/manual/6.3.0/_sources/cdist-troubleshooting.rst.txt Normal file
View file

@ -0,0 +1,64 @@
Troubleshooting
===============
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.
An example script would be something like this:
.. code-block:: sh
% cat ~/.cdist/manifest/init
"$__manifest/special"
% cat ~/.cdist/manifest/special
#!/bin/sh
echo "Here is an unclean exiting script"
somecommandthatdoesnotexist
echo "I continue here although previous command failed"
We can clearly see that **somecommandthatdoesnotexist**
will fail in ~/.cdist/manifest/special. But as the custom
script is not called with the -e flag (exit on failure) of shell,
it does not lead to an error. And thus cdist sees the exit 0
code of the last echo line instead of the failing command.
All scripts executed by cdist carry the -e flag.
To prevent the above from happening, there are three solutions available,
two of which can be used in the calling script:
.. code-block:: sh
# Execute as before, but abort on failure
sh -e "$__manifest/special"
# Source the script in our namespace, runs in a set -e environment:
. "$__manifest/special"
The third solution is to include a shebang header in every script
you write to use the -e flag:
.. code-block:: sh
% cat ~/.cdist/manifest/special
#!/bin/sh -e
...
Using debug dump helper script
------------------------------
Since cdist stores data to local cache that can be used for debugging there
is a helper script that dumps data from local cache,
`cdist-dump <man1/cdist-dump.html>`_.
For more info see:
.. code-block:: sh
cdist-dump -h
Or from cdist git cloned directory:
.. code-block:: sh
./scripts/cdist-dump -h

524
src/extra/manual/6.3.0/_sources/cdist-type.rst.txt Normal file
View file

@ -0,0 +1,524 @@
cdist type
==========
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
--------
.. 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:
.. code-block:: sh
# Creates empty file /etc/cdist-configured
__file /etc/cdist-configured --type file
# Ensure tree is installed
__package tree --state installed
A list of supported types can be found in the `cdist reference <cdist-reference.html>`_ manpage.
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
system. Singleton types do not take an object name as argument.
Example:
.. code-block:: sh
# __issue type manages /etc/issue
__issue
# Probably your own type - singletons may use parameters
__myfancysingleton --colour green
Config types
------------
By default types are used with config command. These are types that are not
flagged by any known command flag. If a type is marked then it will be skipped
with config command.
Install types
-------------
If a type is flagged with 'install' flag then it is used only with install command.
With other commands, i.e. config, these types are skipped if used.
Nonparallel types
-----------------
If a type is flagged with 'nonparallel' flag then its objects cannot be run in parallel
when using -j option. Example of such a type is __package_dpkg type where dpkg itself
prevents to be run in more than one instance.
Deprecated types
-----------------
If a type is flagged with 'deprecated' marker then it is considered deprecated.
When it is used cdist writes warning line. If 'deprecated' marker has content
then this content is printed as a deprecation messages, e.g.:
.. code-block:: sh
$ ls -l deprecated
-rw-r--r-- 1 darko darko 71 May 20 18:30 deprecated
$ cat deprecated
This type is deprecated. It will be removed in the next minor release.
$ echo '__foo foo' | ./bin/cdist config -i - 185.203.112.26
WARNING: 185.203.112.26: Type __foo is deprecated: This type is deprecated. It will be removed in the next minor release.
If 'deprecated' marker has no content then general message is printed, e.g.:
.. code-block:: sh
$ ls -l deprecated
-rw-r--r-- 1 darko darko 0 May 20 18:36 deprecated
$ echo '__bar foo' | ./bin/cdist config -i - 185.203.112.26
WARNING: 185.203.112.26: Type __bar is deprecated.
How to write a new type
-----------------------
A type consists of
- parameter (optional)
- manifest (optional)
- singleton (optional)
- explorer (optional)
- gencode (optional)
- nonparallel (optional)
Types are stored below cdist/conf/type/. Their name should always be prefixed with
two underscores (__) to prevent collisions with other executables in $PATH.
To implement a new type, create the directory **cdist/conf/type/__NAME**.
Type manifest and gencode can be written in any language. They just need to be
executable and have a proper shebang. If they are not executable then cdist assumes
they are written in shell so they are executed using '/bin/sh -e' or 'CDIST_LOCAL_SHELL'.
For executable shell code it is suggested that shebang is '#!/bin/sh -e'.
For creating type skeleton you can use helper script
`cdist-new-type <man1/cdist-new-type.html>`_.
Defining parameters
-------------------
Every type consists of required, optional and boolean parameters, which must
each be declared in a newline separated file in **parameter/required**,
**parameter/required_multiple**, **parameter/optional**,
**parameter/optional_multiple** and **parameter/boolean**.
Parameters which are allowed multiple times should be listed in
required_multiple or optional_multiple respectively. All other parameters
follow the standard unix behaviour "the last given wins".
If either is missing, the type will have no required, no optional, no boolean
or no parameters at all.
Default values for optional parameters can be predefined in
**parameter/default/<name>**.
Example:
.. code-block:: sh
echo servername >> cdist/conf/type/__nginx_vhost/parameter/required
echo logdirectory >> cdist/conf/type/__nginx_vhost/parameter/optional
echo loglevel >> cdist/conf/type/__nginx_vhost/parameter/optional
mkdir cdist/conf/type/__nginx_vhost/parameter/default
echo warning > cdist/conf/type/__nginx_vhost/parameter/default/loglevel
echo server_alias >> cdist/conf/type/__nginx_vhost/parameter/optional_multiple
echo use_ssl >> cdist/conf/type/__nginx_vhost/parameter/boolean
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
represented by file existence. File exists -> True,
file does not exist -> False
Example: (e.g. in cdist/conf/type/__nginx_vhost/manifest)
.. code-block:: sh
# required parameter
servername="$(cat "$__object/parameter/servername")"
# optional parameter
if [ -f "$__object/parameter/logdirectory" ]; then
logdirectory="$(cat "$__object/parameter/logdirectory")"
fi
# optional parameter with predefined default
loglevel="$(cat "$__object/parameter/loglevel")"
# boolean parameter
if [ -f "$__object/parameter/use_ssl" ]; then
# file exists -> True
# do some fancy ssl stuff
fi
# parameter with multiple values
if [ -f "$__object/parameter/server_alias" ]; then
for alias in $(cat "$__object/parameter/server_alias"); do
echo $alias > /some/where/useful
done
fi
Deprecated parameters
---------------------
To deprecate type parameters one can declare a file for each deprecated
parameter under **parameter/deprecated** directory.
When such parameter is used cdist writes warning line with deprecation message.
If such file has content then this content is printed as deprecation message.
If there is no content then generic parameter deprecation message is printed.
Example:
.. code-block:: sh
$ ls parameter/deprecated/
eggs spam
$ cat parameter/deprecated/eggs
eggs parameter is deprecated, please use multiple egg parameter.
$ cat parameter/deprecated/spam
$ echo '__foo foo --foo foo --eggs eggs' | ./bin/cdist config -i - 185.203.112.26
WARNING: 185.203.112.26: eggs parameter of type __foo is deprecated: eggs parameter is deprecated, please use multiple egg parameter.
$ echo '__foo foo --foo foo --eggs eggs --spam spam' | ./bin/cdist config -i - 185.203.112.26
WARNING: 185.203.112.26: spam parameter of type __foo is deprecated.
WARNING: 185.203.112.26: eggs parameter of type __foo is deprecated: eggs parameter is deprecated, please use multiple egg parameter.
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.
Example use of a type: (e.g. in cdist/conf/type/__archlinux_hostname)
.. code-block:: sh
__file /etc/rc.conf --source - << eof
...
HOSTNAME="$__target_host"
...
eof
If you have not seen this syntax (<< eof) before, it may help you to read
about "here documents".
In the __file type, stdin is used as source for the file, if - is used for source:
.. code-block:: sh
if [ -f "$__object/parameter/source" ]; then
source="$(cat "$__object/parameter/source")"
if [ "$source" = "-" ]; then
source="$__object/stdin"
fi
....
Stdin inside a loop
~~~~~~~~~~~~~~~~~~~
Since cdist saves type's stdin content in the object as **$__object/stdin**,
so it can be accessed in manifest and gencode-* scripts, this can lead to
unexpected behavior. For example, suppose you have some type with the following
in its manifest:
.. code-block:: sh
if [ -f "$__object/parameter/foo" ]
then
while read -r l
do
__file "$l"
echo "$l" >&2
done < "$__object/parameter/foo"
fi
and init manifest:
.. code-block:: sh
__foo foo --foo a --foo b --foo c
You expect that manifest stderr content is:
.. code-block:: sh
a
b
c
and that files *a*, *b* and *c* are created. But all you get in manifest stderr
is:
.. code-block:: sh
a
and only *a* file is created.
When redirecting parameter *foo* file content to while's stdin that means that all
commands in while body have this same stdin. So when *__file* type gets executed,
cdist saves its stdin which means it gets the remaining content of parameter *foo*
file, i.e.:
.. code-block:: sh
b
c
The solution is to make sure that your types inside such loops get their stdin
from somewhere else, e.g. for the above problem *__file* type can get empty
stdin from */dev/null*:
.. code-block:: sh
if [ -f "$__object/parameter/foo" ]
then
while read -r l
do
__file "$l" < /dev/null
echo "$l" >&2
done < "$__object/parameter/foo"
fi
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
a shortened version looks like this:
.. code-block:: sh
os="$(cat "$__global/explorer/os")"
case "$os" in
archlinux) type="pacman" ;;
debian|ubuntu) type="apt" ;;
gentoo) type="emerge" ;;
*)
echo "Don't know how to manage packages on: $os" >&2
exit 1
;;
esac
__package_$type "$@"
As you can see, the type can reference different environment variables,
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 <cdist-manifest.html>`_.
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
directory:
.. code-block:: sh
touch cdist/conf/type/__NAME/singleton
This will also change the way your type must be called:
.. code-block:: sh
__YOURTYPE --parameter value
As you can see, the object ID is omitted, because it does not make any sense,
if your type can be used only once.
Install - type with install command
-----------------------------------
If you want a type to be used with install command, you must mark it as
install: create the (empty) file "install" in your type directory:
.. code-block:: sh
touch cdist/conf/type/__install_NAME/install
With other commands, i.e. config, it will be skipped if used.
Nonparallel - only one instance can be run at a time
----------------------------------------------------
If objects of a type must not or cannot be run in parallel when using -j
option, you must mark it as nonparallel: create the (empty) file "nonparallel"
in your type directory:
.. code-block:: sh
touch cdist/conf/type/__NAME/nonparallel
For example, package types are nonparallel types.
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.
The explorers are stored under the "explorer" directory below the type.
It could for instance contain code to check the md5sum of a file on the
client, like this (shortened version from the type __file):
.. code-block:: sh
if [ -f "$__object/parameter/destination" ]; then
destination="$(cat "$__object/parameter/destination")"
else
destination="/$__object_id"
fi
if [ -e "$destination" ]; then
md5sum < "$destination"
fi
Writing the gencode script
--------------------------
There are two gencode scripts: **gencode-local** and **gencode-remote**.
The output of gencode-local is executed locally, whereas
the output of gencode-remote is executed on the target.
The gencode scripts can make use of the parameters, the global explorers
and the type specific explorers.
If the gencode scripts encounters an error, it should print diagnostic
messages to stderr and exit non-zero. If you need to debug the gencode
script, you can write to stderr:
.. code-block:: sh
# Debug output to stderr
echo "My fancy debug line" >&2
# Output to be saved by cdist for execution on the target
echo "touch /etc/cdist-configured"
Notice: if you use __remote_copy or __remote_exec directly in your scripts
then for IPv6 address with __remote_copy execution you should enclose IPv6
address in square brackets. The same applies to __remote_exec if it behaves
the same as ssh for some options where colon is a delimiter, as for -L ssh
option (see :strong:`ssh`\ (1) and :strong:`scp`\ (1)).
Variable access from the generated scripts
------------------------------------------
In the generated scripts, you have access to the following cdist variables
- __object
- __object_id
but only for read operations, means there is no back copy of this
files after the script execution.
So when you generate a script with the following content, it will work:
.. code-block:: sh
if [ -f "$__object/parameter/name" ]; then
name="$(cat "$__object/parameter/name")"
else
name="$__object_id"
fi
Environment variable usage idiom
--------------------------------
In type scripts you can support environment variables with default values if
environment variable is unset or null by using **${parameter:-[word]}**
parameter expansion.
Example using mktemp in a portable way that supports TMPDIR environment variable.
.. code-block:: sh
tempfile=$(mktemp "${TMPDIR:-/tmp}/cdist.XXXXXXXXXX")
Log level in types
------------------
cdist log level can be accessed from __cdist_log_level variable.One of:
+----------------+-----------------+
| Log level | Log level value |
+================+=================+
| OFF | 60 |
+----------------+-----------------+
| ERROR | 40 |
+----------------+-----------------+
| WARNING | 30 |
+----------------+-----------------+
| INFO | 20 |
+----------------+-----------------+
| VERBOSE | 15 |
+----------------+-----------------+
| DEBUG | 10 |
+----------------+-----------------+
| TRACE | 5 |
+----------------+-----------------+
It is available for initial manifest, explorer, type manifest,
type explorer, type gencode.
Detecting dry run
-----------------
If ``$__cdist_dry_run`` environment variable is set, then it's dry run.
It is available for initial manifest, explorer, type manifest,
type explorer, type gencode.
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
on the target, there must be another type that provides this tool and the first
type should create an object of the specific type.
If your type wants to save temporary data, that may be used by other types
later on (for instance \__file), you can save them in the subdirectory
"files" below $__object (but you must create it yourself).
cdist will not touch this directory.
If your type contains static files, it's also recommended to place them in
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
-----------------------------------------
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 hacking <cdist-hacker.html>`_ on
how to submit it.

160
src/extra/manual/6.3.0/_sources/cdist-types.rst.txt Normal file
View file

@ -0,0 +1,160 @@
cdist types
===========
.. toctree::
:titlesonly:
__acl <man7/cdist-type__acl>
__apt_default_release <man7/cdist-type__apt_default_release>
__apt_key <man7/cdist-type__apt_key>
__apt_key_uri <man7/cdist-type__apt_key_uri>
__apt_mark <man7/cdist-type__apt_mark>
__apt_norecommends <man7/cdist-type__apt_norecommends>
__apt_ppa <man7/cdist-type__apt_ppa>
__apt_source <man7/cdist-type__apt_source>
__apt_update_index <man7/cdist-type__apt_update_index>
__block <man7/cdist-type__block>
__ccollect_source <man7/cdist-type__ccollect_source>
__cdist <man7/cdist-type__cdist>
__cdistmarker <man7/cdist-type__cdistmarker>
__check_messages <man7/cdist-type__check_messages>
__chroot_mount <man7/cdist-type__chroot_mount>
__chroot_umount <man7/cdist-type__chroot_umount>
__clean_path <man7/cdist-type__clean_path>
__config_file <man7/cdist-type__config_file>
__consul <man7/cdist-type__consul>
__consul_agent <man7/cdist-type__consul_agent>
__consul_check <man7/cdist-type__consul_check>
__consul_reload <man7/cdist-type__consul_reload>
__consul_service <man7/cdist-type__consul_service>
__consul_template <man7/cdist-type__consul_template>
__consul_template_template <man7/cdist-type__consul_template_template>
__consul_watch_checks <man7/cdist-type__consul_watch_checks>
__consul_watch_event <man7/cdist-type__consul_watch_event>
__consul_watch_key <man7/cdist-type__consul_watch_key>
__consul_watch_keyprefix <man7/cdist-type__consul_watch_keyprefix>
__consul_watch_nodes <man7/cdist-type__consul_watch_nodes>
__consul_watch_service <man7/cdist-type__consul_watch_service>
__consul_watch_services <man7/cdist-type__consul_watch_services>
__cron <man7/cdist-type__cron>
__daemontools <man7/cdist-type__daemontools>
__daemontools_service <man7/cdist-type__daemontools_service>
__debconf_set_selections <man7/cdist-type__debconf_set_selections>
__directory <man7/cdist-type__directory>
__docker <man7/cdist-type__docker>
__docker_compose <man7/cdist-type__docker_compose>
__docker_config <man7/cdist-type__docker_config>
__docker_secret <man7/cdist-type__docker_secret>
__docker_stack <man7/cdist-type__docker_stack>
__docker_swarm <man7/cdist-type__docker_swarm>
__dog_vdi <man7/cdist-type__dog_vdi>
__dot_file <man7/cdist-type__dot_file>
__file <man7/cdist-type__file>
__filesystem <man7/cdist-type__filesystem>
__firewalld_rule <man7/cdist-type__firewalld_rule>
__firewalld_start <man7/cdist-type__firewalld_start>
__git <man7/cdist-type__git>
__go_get <man7/cdist-type__go_get>
__golang_from_vendor <man7/cdist-type__golang_from_vendor>
__grafana_dashboard <man7/cdist-type__grafana_dashboard>
__group <man7/cdist-type__group>
__hostname <man7/cdist-type__hostname>
__hosts <man7/cdist-type__hosts>
__install_bootloader_grub <man7/cdist-type__install_bootloader_grub>
__install_chroot_mount <man7/cdist-type__install_chroot_mount>
__install_chroot_umount <man7/cdist-type__install_chroot_umount>
__install_config <man7/cdist-type__install_config>
__install_coreos <man7/cdist-type__install_coreos>
__install_directory <man7/cdist-type__install_directory>
__install_file <man7/cdist-type__install_file>
__install_fstab <man7/cdist-type__install_fstab>
__install_generate_fstab <man7/cdist-type__install_generate_fstab>
__install_mkfs <man7/cdist-type__install_mkfs>
__install_mount <man7/cdist-type__install_mount>
__install_partition_msdos <man7/cdist-type__install_partition_msdos>
__install_partition_msdos_apply <man7/cdist-type__install_partition_msdos_apply>
__install_reboot <man7/cdist-type__install_reboot>
__install_reset_disk <man7/cdist-type__install_reset_disk>
__install_stage <man7/cdist-type__install_stage>
__install_umount <man7/cdist-type__install_umount>
__iptables_apply <man7/cdist-type__iptables_apply>
__iptables_rule <man7/cdist-type__iptables_rule>
__issue <man7/cdist-type__issue>
__jail <man7/cdist-type__jail>
__jail_freebsd10 <man7/cdist-type__jail_freebsd10>
__jail_freebsd9 <man7/cdist-type__jail_freebsd9>
__key_value <man7/cdist-type__key_value>
__keyboard <man7/cdist-type__keyboard>
__letsencrypt_cert <man7/cdist-type__letsencrypt_cert>
__line <man7/cdist-type__line>
__link <man7/cdist-type__link>
__locale <man7/cdist-type__locale>
__locale_system <man7/cdist-type__locale_system>
__motd <man7/cdist-type__motd>
__mount <man7/cdist-type__mount>
__mysql_database <man7/cdist-type__mysql_database>
__openldap_server <man7/cdist-type__openldap_server>
__package <man7/cdist-type__package>
__package_apk <man7/cdist-type__package_apk>
__package_apt <man7/cdist-type__package_apt>
__package_dpkg <man7/cdist-type__package_dpkg>
__package_emerge <man7/cdist-type__package_emerge>
__package_emerge_dependencies <man7/cdist-type__package_emerge_dependencies>
__package_luarocks <man7/cdist-type__package_luarocks>
__package_opkg <man7/cdist-type__package_opkg>
__package_pacman <man7/cdist-type__package_pacman>
__package_pip <man7/cdist-type__package_pip>
__package_pkg_freebsd <man7/cdist-type__package_pkg_freebsd>
__package_pkg_openbsd <man7/cdist-type__package_pkg_openbsd>
__package_pkgng_freebsd <man7/cdist-type__package_pkgng_freebsd>
__package_rubygem <man7/cdist-type__package_rubygem>
__package_update_index <man7/cdist-type__package_update_index>
__package_upgrade_all <man7/cdist-type__package_upgrade_all>
__package_yum <man7/cdist-type__package_yum>
__package_zypper <man7/cdist-type__package_zypper>
__pacman_conf <man7/cdist-type__pacman_conf>
__pacman_conf_integrate <man7/cdist-type__pacman_conf_integrate>
__pf_apply <man7/cdist-type__pf_apply>
__pf_ruleset <man7/cdist-type__pf_ruleset>
__ping <man7/cdist-type__ping>
__postfix <man7/cdist-type__postfix>
__postfix_master <man7/cdist-type__postfix_master>
__postfix_postconf <man7/cdist-type__postfix_postconf>
__postfix_postmap <man7/cdist-type__postfix_postmap>
__postfix_reload <man7/cdist-type__postfix_reload>
__postgres_database <man7/cdist-type__postgres_database>
__postgres_extension <man7/cdist-type__postgres_extension>
__postgres_role <man7/cdist-type__postgres_role>
__process <man7/cdist-type__process>
__prometheus_alertmanager <man7/cdist-type__prometheus_alertmanager>
__prometheus_exporter <man7/cdist-type__prometheus_exporter>
__prometheus_server <man7/cdist-type__prometheus_server>
__pyvenv <man7/cdist-type__pyvenv>
__qemu_img <man7/cdist-type__qemu_img>
__rbenv <man7/cdist-type__rbenv>
__rsync <man7/cdist-type__rsync>
__rvm <man7/cdist-type__rvm>
__rvm_gem <man7/cdist-type__rvm_gem>
__rvm_gemset <man7/cdist-type__rvm_gemset>
__rvm_ruby <man7/cdist-type__rvm_ruby>
__sensible_editor <man7/cdist-type__sensible_editor>
__ssh_authorized_key <man7/cdist-type__ssh_authorized_key>
__ssh_authorized_keys <man7/cdist-type__ssh_authorized_keys>
__ssh_dot_ssh <man7/cdist-type__ssh_dot_ssh>
__staged_file <man7/cdist-type__staged_file>
__start_on_boot <man7/cdist-type__start_on_boot>
__sysctl <man7/cdist-type__sysctl>
__systemd_unit <man7/cdist-type__systemd_unit>
__timezone <man7/cdist-type__timezone>
__ufw <man7/cdist-type__ufw>
__ufw_rule <man7/cdist-type__ufw_rule>
__update_alternatives <man7/cdist-type__update_alternatives>
__user <man7/cdist-type__user>
__user_groups <man7/cdist-type__user_groups>
__xymon_apache <man7/cdist-type__xymon_apache>
__xymon_client <man7/cdist-type__xymon_client>
__xymon_config <man7/cdist-type__xymon_config>
__xymon_server <man7/cdist-type__xymon_server>
__yum_repo <man7/cdist-type__yum_repo>
__zypper_repo <man7/cdist-type__zypper_repo>
__zypper_service <man7/cdist-type__zypper_service>

188
src/extra/manual/6.3.0/_sources/cdist-upgrade.rst.txt Normal file
View file

@ -0,0 +1,188 @@
How to upgrade cdist
====================
Update the git installation
---------------------------
To upgrade cdist in the current branch use
.. code-block:: sh
git pull
# Also update the manpages
make 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 incompatibilities.
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 incompatibilities.
Updating from 1.2 to 1.3
~~~~~~~~~~~~~~~~~~~~~~~~
Rename **gencode** of every type to **gencode-remote**.
Updating from 1.1 to 1.2
~~~~~~~~~~~~~~~~~~~~~~~~
No incompatibilities.
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
src/extra/manual/6.3.0/_sources/cdist-why.rst.txt Normal file
View 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 little on a target system. Even better,
in almost all cases all dependencies are usually fulfilled.
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,
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 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
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.

44
src/extra/manual/6.3.0/_sources/index.rst.txt Normal file
View file

@ -0,0 +1,44 @@
cdist - usable configuration management
=======================================
cdist is a usable configuration management system.
It adheres to the KISS principle and
is being used in small up to enterprise grade environments.
.. toctree::
:maxdepth: 3
:glob:
:numbered:
:hidden:
cdist-why
cdist-features
cdist-os
cdist-install
cdist-upgrade
cdist-support
cdist-quickstart
cdist-real-world
man1/cdist
man1/cdist-dump
man1/cdist-new-type
cdist-bootstrap
cdist-configuration
cdist-manifest
cdist-type
cdist-types
cdist-explorer
cdist-messaging
cdist-parallelization
cdist-inventory
cdist-preos
cdist-integration
cdist-reference
cdist-best-practice
cdist-stages
cdist-cache
cdist-saving-output-streams
cdist-remote-exec-copy
cdist-hacker
cdist-troubleshooting

110
src/extra/manual/6.3.0/_sources/man1/cdist-dump.rst.txt Normal file
View file

@ -0,0 +1,110 @@
cdist-dump(1)
=============
NAME
----
cdist-dump - Dump data from local cdist cache
SYNOPSIS
--------
::
cdist-dump [options] [host...]
DESCRIPTION
-----------
cdist-dump is a helper script that dumps data from local cdist cache for
specified hosts. If host is not specified then all data from cache directory
is dumped. Default cache directory is '~/.cdist/cache'.
cdist-dump can be used for debugging existing types, host configuration and
new types.
OPTIONS
-------
**-a**
dump all
**-C CACHE-DIR**
use specified CACHE-DIR (default: ~/.cdist/cache)
**-c**
dump code-*
**-d DELIMITER**
delimiter used for filename and line number prefix (default: ':')
**-E**
dump global explorers
**-e**
dump type explorers
**-F**
disable filename prefix (enabled by default)
**-f**
enable filename prefix (default)
**-g**
dump gencode-*
**-h**
show this help screen and exit
**-L**
disable line number prefix (default)
**-l**
enable line number prefix (disabled by default)
**-m**
dump messages
**-o**
dump executions' stdout
**-p**
dump parameters
**-r**
dump executions' stderr
**-V**
show version and exit
**-v**
increase verbosity
EXAMPLES
--------
.. code-block:: sh
# Dump all
% cdist-dump -a
# Dump only code-* output
% cdist-dump -c
SEE ALSO
--------
:strong:`cdist`\ (1)
AUTHORS
-------
Darko Poljak <darko.poljak--@--ungleich.ch>
COPYING
-------
Copyright \(C) 2019 Darko Poljak. Free use of this software is
granted under the terms of the GNU General Public License v3 or later (GPLv3+).

74
src/extra/manual/6.3.0/_sources/man1/cdist-new-type.rst.txt Normal file
View file

@ -0,0 +1,74 @@
cdist-new-type(1)
=================
NAME
----
cdist-new-type - Create new type skeleton
SYNOPSIS
--------
::
cdist-new-type TYPE-NAME AUTHOR-NAME AUTHOR-EMAIL [TYPE-BASE-PATH]
DESCRIPTION
-----------
cdist-new-type is a helper script that creates new type skeleton.
It is then up to the type author to finish the type.
It creates skeletons for the following files:
* man.rst
* manifest
* gencode-remote.
Upon creation it prints the path to the newly created type directory.
ARGUMENTS
---------
**TYPE-NAME**
Name of the new type.
**AUTHOR-NAME**
Type author's full name.
**AUTHOR-NAME**
Type author's email.
**TYPE-BASE-PATH**
Path to the base directory of the type. If not set it defaults
to '$PWD/type'.
EXAMPLES
--------
.. code-block:: sh
# Create new type __foo in ~/.cdist directory.
$ cd ~/.cdist
$ cdist-new-type '__foo' 'Foo Bar' 'foo.bar at foobar.org'
/home/foo/.cdist/type/__foo
SEE ALSO
--------
:strong:`cdist`\ (1)
AUTHORS
-------
| Steven Armstrong <steven-cdist--@--armstrong.cc>
| Darko Poljak <darko.poljak--@--ungleich.ch>
COPYING
-------
Copyright \(C) 2019 Steven Armstrong, Darko Poljak. Free use of this software is
granted under the terms of the GNU General Public License v3 or later (GPLv3+).

919
src/extra/manual/6.3.0/_sources/man1/cdist.rst.txt Normal file
View file

@ -0,0 +1,919 @@
cdist(1)
========
NAME
----
cdist - Usable Configuration Management
SYNOPSIS
--------
::
cdist [-h] [-V] {banner,config,install,inventory,preos,shell} ...
cdist banner [-h] [-l LOGLEVEL] [-q] [-v]
cdist config [-h] [-l LOGLEVEL] [-q] [-v] [-b] [-g CONFIG_FILE] [-4]
[-6] [-C CACHE_PATH_PATTERN] [-c CONF_DIR] [-i MANIFEST]
[-j [JOBS]] [-n] [-o OUT_PATH] [-P]
[-R [{tar,tgz,tbz2,txz}]] [-r REMOTE_OUT_PATH]
[--remote-copy REMOTE_COPY] [--remote-exec REMOTE_EXEC]
[-S] [-I INVENTORY_DIR] [-A] [-a] [-f HOSTFILE]
[-p [HOST_MAX]] [-s] [-t]
[host [host ...]]
cdist install [-h] [-l LOGLEVEL] [-q] [-v] [-b] [-g CONFIG_FILE] [-4]
[-6] [-C CACHE_PATH_PATTERN] [-c CONF_DIR] [-i MANIFEST]
[-j [JOBS]] [-n] [-o OUT_PATH] [-P]
[-R [{tar,tgz,tbz2,txz}]] [-r REMOTE_OUT_PATH]
[--remote-copy REMOTE_COPY] [--remote-exec REMOTE_EXEC]
[-S] [-I INVENTORY_DIR] [-A] [-a] [-f HOSTFILE]
[-p [HOST_MAX]] [-s] [-t]
[host [host ...]]
cdist inventory [-h] {add-host,add-tag,del-host,del-tag,list} ...
cdist inventory add-host [-h] [-l LOGLEVEL] [-q] [-v] [-b]
[-g CONFIG_FILE] [-I INVENTORY_DIR]
[-f HOSTFILE]
[host [host ...]]
cdist inventory add-tag [-h] [-l LOGLEVEL] [-q] [-v] [-b]
[-g CONFIG_FILE] [-I INVENTORY_DIR]
[-f HOSTFILE] [-T TAGFILE] [-t TAGLIST]
[host [host ...]]
cdist inventory del-host [-h] [-l LOGLEVEL] [-q] [-v] [-b]
[-g CONFIG_FILE] [-I INVENTORY_DIR] [-a]
[-f HOSTFILE]
[host [host ...]]
cdist inventory del-tag [-h] [-l LOGLEVEL] [-q] [-v] [-b]
[-g CONFIG_FILE] [-I INVENTORY_DIR] [-a]
[-f HOSTFILE] [-T TAGFILE] [-t TAGLIST]
[host [host ...]]
cdist inventory list [-h] [-l LOGLEVEL] [-q] [-v] [-b] [-g CONFIG_FILE]
[-I INVENTORY_DIR] [-a] [-f HOSTFILE] [-H] [-t]
[host [host ...]]
cdist preos [-h] [-l LOGLEVEL] [-q] [-v] [-c CONF_DIR] [-L] [preos] ...
cdist preos [preos-options] debian [-h] [-l LOGLEVEL] [-q] [-v] [-b] [-a ARCH] [-B]
[-C] [-c CDIST_PARAMS] [-D DRIVE] [-e REMOTE_EXEC]
[-i MANIFEST] [-k KEYFILE ] [-m MIRROR]
[-P ROOT_PASSWORD] [-p PXE_BOOT_DIR] [-r]
[-S SCRIPT] [-s SUITE] [-y REMOTE_COPY]
target_dir
cdist preos [preos-options] devuan [-h] [-l LOGLEVEL] [-q] [-v] [-b] [-a ARCH] [-B]
[-C] [-c CDIST_PARAMS] [-D DRIVE] [-e REMOTE_EXEC]
[-i MANIFEST] [-k KEYFILE ] [-m MIRROR]
[-P ROOT_PASSWORD] [-p PXE_BOOT_DIR] [-r]
[-S SCRIPT] [-s SUITE] [-y REMOTE_COPY]
target_dir
cdist preos [preos-options] ubuntu [-h] [-l LOGLEVEL] [-q] [-v] [-b] [-a ARCH] [-B]
[-C] [-c CDIST_PARAMS] [-D DRIVE] [-e REMOTE_EXEC]
[-i MANIFEST] [-k KEYFILE ] [-m MIRROR]
[-P ROOT_PASSWORD] [-p PXE_BOOT_DIR] [-r]
[-S SCRIPT] [-s SUITE] [-y REMOTE_COPY]
target_dir
cdist shell [-h] [-l LOGLEVEL] [-q] [-v] [-s SHELL]
DESCRIPTION
-----------
cdist is the frontend executable to the cdist configuration management.
It supports different subcommands as explained below.
It is written in Python so it requires :strong:`python`\ (1) to be installed.
It requires a minimal Python version 3.2.
GENERAL
-------
All commands accept the following options:
**-h, --help**
Show the help screen.
**-l LOGLEVEL, --log-level LOGLEVEL**
Set the specified verbosity level. The levels, in
order from the lowest to the highest, are: ERROR (-1),
WARNING (0), INFO (1), VERBOSE (2), DEBUG (3), TRACE (4
or higher). If used along with -v then -v increases
last set value and -l overwrites last set value.
**-q, --quiet**
Quiet mode: disables logging, including WARNING and ERROR.
**-v, --verbose**
Increase the verbosity level. Every instance of -v
increments the verbosity level by one. Its default
value is 0 which includes ERROR and WARNING levels.
The levels, in order from the lowest to the highest,
are: ERROR (-1), WARNING (0), INFO (1), VERBOSE (2),
DEBUG (3), TRACE (4 or higher). If used along with -l
then -l overwrites last set value and -v increases
last set value.
**-V, --version**
Show version and exit.
BANNER
------
Displays the cdist banner. Useful for printing
cdist posters - a must have for every office.
CONFIG/INSTALL
--------------
Configure/install one or more hosts.
Install command is currently in beta.
**-4, --force-ipv4**
Force to use IPv4 addresses only. No influence for
custom remote commands.
**-6, --force-ipv6**
Force to use IPv6 addresses only. No influence for
custom remote commands.
**-A, --all-tagged**
Use all hosts present in tags db. Currently in beta.
**-a, --all**
List hosts that have all specified tags, if -t/--tag
is specified.
**-b, --beta**
Enable beta functionality.
**-C CACHE_PATH_PATTERN, --cache-path-pattern CACHE_PATH_PATTERN**
Specify custom cache path pattern. If it is not set then
default hostdir is used. For more info on format see
:strong:`CACHE PATH PATTERN FORMAT` below.
**-c CONF_DIR, --conf-dir CONF_DIR**
Add a configuration directory. Can be specified multiple times.
If configuration directories contain conflicting types, explorers or
manifests, then the last one found is used.
**-f HOSTFILE, --file HOSTFILE**
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
:strong:`HOSTFILE FORMAT` below.
**-g CONFIG_FILE, --config-file CONFIG_FILE**
Use specified custom configuration file.
**-I INVENTORY_DIR, --inventory INVENTORY_DIR**
Use specified custom inventory directory. Inventory
directory is set up by the following rules: if cdist
configuration resolves this value then specified
directory is used, if HOME env var is set then
~/.cdit/inventory is used, otherwise distribution
inventory directory is used.
**-i MANIFEST, --initial-manifest MANIFEST**
Path to a cdist manifest or - to read from stdin.
**-j [JOBS], --jobs [JOBS]**
Operate in parallel in specified maximum number of
jobs. Global explorers, object prepare and object run
are supported. Without argument CPU count is used by
default.
**-n, --dry-run**
Do not execute code.
**-o OUT_PATH, --out-dir OUT_PATH**
Directory to save cdist output in.
**-P, --timestamp**
Timestamp log messages with the current local date and time
in the format: YYYYMMDDHHMMSS.us.
**-p [HOST_MAX], --parallel [HOST_MAX]**
Operate on multiple hosts in parallel for specified
maximum hosts at a time. Without argument CPU count is
used by default.
**-R [{tar,tgz,tbz2,txz}], --use-archiving [{tar,tgz,tbz2,txz}]**
Operate by using archiving with compression where
appropriate. Supported values are: tar - tar archive,
tgz - gzip tar archive (the default), tbz2 - bzip2 tar
archive and txz - lzma tar archive. Currently in beta.
**-r REMOTE_OUT_PATH, --remote-out-dir REMOTE_OUT_PATH**
Directory to save cdist output in on the target host.
**-S, --disable-saving-output-streams**
Disable saving output streams.
**-s, --sequential**
Operate on multiple hosts sequentially (default).
**--remote-copy REMOTE_COPY**
Command to use for remote copy (should behave like scp).
**--remote-exec REMOTE_EXEC**
Command to use for remote execution (should behave like ssh).
**-t, --tag**
Host is specified by tag, not hostname/address; list
all hosts that contain any of specified tags.
Currently in beta.
HOSTFILE FORMAT
~~~~~~~~~~~~~~~
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.
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.
CACHE PATH PATTERN FORMAT
~~~~~~~~~~~~~~~~~~~~~~~~~
Cache path pattern specifies path for a cache directory subdirectory.
In the path, '%N' will be substituted by the target host, '%h' will
be substituted by the calculated host directory, '%P' will be substituted
by the current process id. All format codes that
:strong:`python` :strong:`datetime.strftime()` function supports, except
'%h', are supported. These date/time directives format cdist config/install
start time.
If empty pattern is specified then default calculated host directory
is used.
Calculated host directory is a hash of a host cdist operates on.
Resulting path is used to specify cache path subdirectory under which
current host cache data are saved.
INVENTORY
---------
Manage inventory database.
Currently in beta with all sub-commands.
INVENTORY ADD-HOST
------------------
Add host(s) to inventory database.
**host**
Host(s) to add.
**-b, --beta**
Enable beta functionality.
**-f HOSTFILE, --file HOSTFILE**
Read additional hosts to add from specified file or
from stdin if '-' (each host on separate line). If no
host or host file is specified then, by default, read
from stdin. Hostfile format is the same as config hostfile format.
**-g CONFIG_FILE, --config-file CONFIG_FILE**
Use specified custom configuration file.
**-I INVENTORY_DIR, --inventory INVENTORY_DIR**
Use specified custom inventory directory. Inventory
directory is set up by the following rules: if cdist
configuration resolves this value then specified
directory is used, if HOME env var is set then
~/.cdit/inventory is used, otherwise distribution
inventory directory is used.
INVENTORY ADD-TAG
-----------------
Add tag(s) to inventory database.
**host**
List of host(s) for which tags are added.
**-b, --beta**
Enable beta functionality.
**-f HOSTFILE, --file HOSTFILE**
Read additional hosts to add tags from specified file
or from stdin if '-' (each host on separate line). If
no host or host file is specified then, by default,
read from stdin. If no tags/tagfile nor hosts/hostfile
are specified then tags are read from stdin and are
added to all hosts. Hostfile format is the same as config hostfile format.
**-g CONFIG_FILE, --config-file CONFIG_FILE**
Use specified custom configuration file.
**-I INVENTORY_DIR, --inventory INVENTORY_DIR**
Use specified custom inventory directory. Inventory
directory is set up by the following rules: if cdist
configuration resolves this value then specified
directory is used, if HOME env var is set then
~/.cdit/inventory is used, otherwise distribution
inventory directory is used.
**-T TAGFILE, --tag-file TAGFILE**
Read additional tags to add from specified file or
from stdin if '-' (each tag on separate line). If no
tag or tag file is specified then, by default, read
from stdin. If no tags/tagfile nor hosts/hostfile are
specified then tags are read from stdin and are added
to all hosts. Tagfile format is the same as config hostfile format.
**-t TAGLIST, --taglist TAGLIST**
Tag list to be added for specified host(s), comma
separated values.
INVENTORY DEL-HOST
------------------
Delete host(s) from inventory database.
**host**
Host(s) to delete.
**-a, --all**
Delete all hosts.
**-b, --beta**
Enable beta functionality.
**-f HOSTFILE, --file HOSTFILE**
Read additional hosts to delete from specified file or
from stdin if '-' (each host on separate line). If no
host or host file is specified then, by default, read
from stdin. Hostfile format is the same as config hostfile format.
**-g CONFIG_FILE, --config-file CONFIG_FILE**
Use specified custom configuration file.
**-I INVENTORY_DIR, --inventory INVENTORY_DIR**
Use specified custom inventory directory. Inventory
directory is set up by the following rules: if cdist
configuration resolves this value then specified
directory is used, if HOME env var is set then
~/.cdit/inventory is used, otherwise distribution
inventory directory is used.
INVENTORY DEL-TAG
-----------------
Delete tag(s) from inventory database.
**host**
List of host(s) for which tags are deleted.
**-a, --all**
Delete all tags for specified host(s).
**-b, --beta**
Enable beta functionality.
**-f HOSTFILE, --file HOSTFILE**
Read additional hosts to delete tags for from
specified file or from stdin if '-' (each host on
separate line). If no host or host file is specified
then, by default, read from stdin. If no tags/tagfile
nor hosts/hostfile are specified then tags are read
from stdin and are deleted from all hosts. Hostfile
format is the same as config hostfile format.
**-g CONFIG_FILE, --config-file CONFIG_FILE**
Use specified custom configuration file.
**-I INVENTORY_DIR, --inventory INVENTORY_DIR**
Use specified custom inventory directory. Inventory
directory is set up by the following rules: if cdist
configuration resolves this value then specified
directory is used, if HOME env var is set then
~/.cdit/inventory is used, otherwise distribution
inventory directory is used.
**-T TAGFILE, --tag-file TAGFILE**
Read additional tags from specified file or from stdin
if '-' (each tag on separate line). If no tag or tag
file is specified then, by default, read from stdin.
If no tags/tagfile nor hosts/hostfile are specified
then tags are read from stdin and are added to all
hosts. Tagfile format is the same as config hostfile format.
**-t TAGLIST, --taglist TAGLIST**
Tag list to be deleted for specified host(s), comma
separated values.
INVENTORY LIST
--------------
List inventory database.
**host**
Host(s) to list.
**-a, --all**
List hosts that have all specified tags, if -t/--tag
is specified.
**-b, --beta**
Enable beta functionality.
**-f HOSTFILE, --file HOSTFILE**
Read additional hosts to list from specified file or
from stdin if '-' (each host on separate line). If no
host or host file is specified then, by default, list
all. Hostfile format is the same as config hostfile format.
**-g CONFIG_FILE, --config-file CONFIG_FILE**
Use specified custom configuration file.
**-H, --host-only**
Suppress tags listing.
**-I INVENTORY_DIR, --inventory INVENTORY_DIR**
Use specified custom inventory directory. Inventory
directory is set up by the following rules: if cdist
configuration resolves this value then specified
directory is used, if HOME env var is set then
~/.cdit/inventory is used, otherwise distribution
inventory directory is used.
**-t, --tag**
Host is specified by tag, not hostname/address; list
all hosts that contain any of specified tags.
PREOS
-----
Create PreOS.
**-c CONF_DIR, --conf-dir CONF_DIR**
Add configuration directory (one that contains "preos" subdirectory).
**-L, --list-preoses**
List available PreOS-es.
Currently, the following PreOS-es are supported:
* debian
* ubuntu
* devuan
PREOS DEBIAN/DEVUAN
-------------------
**target_dir**
target directory where PreOS will be bootstrapped
**-a ARCH, --arch ARCH**
target debootstrap architecture, by default 'amd64'
**-B, --bootstrap**
do bootstrap step
**-b, --beta**
Enable beta functionality.
**-C, --configure**
do configure step
**-c CDIST_PARAMS, --cdist-params CDIST_PARAMS**
parameters that will be passed to cdist config, by
default '-v' is used
**-D DRIVE, --drive-boot DRIVE**
create bootable PreOS on specified drive
**-e REMOTE_EXEC, --remote-exec REMOTE_EXEC**
remote exec that cdist config will use, by default
internal script is used
**-i MANIFEST, --init-manifest MANIFEST**
init manifest that cdist config will use, by default
internal init manifest is used
**-k KEYFILE, --keyfile KEYFILE**
ssh key files that will be added to cdist config;
'``__ssh_authorized_keys root ...``' type is appended to initial manifest
**-m MIRROR, --mirror MIRROR**
use specified mirror for debootstrap
**-P ROOT_PASSWORD, --root-password ROOT_PASSWORD**
Set specified password for root, generated by default
**-p PXE_BOOT_DIR, --pxe-boot-dir PXE_BOOT_DIR**
PXE boot directory
**-r, --rm-bootstrap-dir**
remove target directory after finishing
**-S SCRIPT, --script SCRIPT**
use specified script for debootstrap
**-s SUITE, --suite SUITE**
suite used for debootstrap, by default 'stable'
**-y REMOTE_COPY, --remote-copy REMOTE_COPY**
remote copy that cdist config will use, by default
internal script is used
PREOS UBUNTU
------------
**target_dir**
target directory where PreOS will be bootstrapped
**-a ARCH, --arch ARCH**
target debootstrap architecture, by default 'amd64'
**-B, --bootstrap**
do bootstrap step
**-b, --beta**
Enable beta functionality.
**-C, --configure**
do configure step
**-c CDIST_PARAMS, --cdist-params CDIST_PARAMS**
parameters that will be passed to cdist config, by
default '-v' is used
**-D DRIVE, --drive-boot DRIVE**
create bootable PreOS on specified drive
**-e REMOTE_EXEC, --remote-exec REMOTE_EXEC**
remote exec that cdist config will use, by default
internal script is used
**-i MANIFEST, --init-manifest MANIFEST**
init manifest that cdist config will use, by default
internal init manifest is used
**-k KEYFILE, --keyfile KEYFILE**
ssh key files that will be added to cdist config;
'``__ssh_authorized_keys root ...``' type is appended to initial manifest
**-m MIRROR, --mirror MIRROR**
use specified mirror for debootstrap
**-P ROOT_PASSWORD, --root-password ROOT_PASSWORD**
Set specified password for root, generated by default
**-p PXE_BOOT_DIR, --pxe-boot-dir PXE_BOOT_DIR**
PXE boot directory
**-r, --rm-bootstrap-dir**
remove target directory after finishing
**-S SCRIPT, --script SCRIPT**
use specified script for debootstrap
**-s SUITE, --suite SUITE**
suite used for debootstrap, by default 'xenial'
**-y REMOTE_COPY, --remote-copy REMOTE_COPY**
remote copy that cdist config will use, by default
internal script is used
SHELL
-----
This command allows you to spawn a shell that enables access
to the types as commands. It can be thought as an
"interactive manifest" environment. See below for example
usage. Its primary use is for debugging type parameters.
**-s SHELL, --shell SHELL**
Select shell to use, defaults to current shell. Used shell should
be POSIX compatible shell.
CONFIGURATION
-------------
cdist obtains configuration data from the following sources in the following
order (from higher to lower precedence):
#. command-line options
#. configuration file specified at command-line
#. configuration file specified in CDIST_CONFIG_FILE environment variable
#. environment variables
#. user's configuration file (first one found of ~/.cdist.cfg, $XDG_CONFIG_HOME/cdist/cdist.cfg, in specified order)
#. system-wide configuration file (/etc/cdist.cfg).
CONFIGURATION FILE FORMAT
~~~~~~~~~~~~~~~~~~~~~~~~~
cdist configuration file is in the INI file format. Currently it supports
only [GLOBAL] section.
The possible keywords and their meanings are as follows:
:strong:`archiving`
Use specified archiving. Valid values include:
'none', 'tar', 'tgz', 'tbz2' and 'txz'.
:strong:`beta`
Enable beta functionality. It recognizes boolean values from
'yes'/'no', 'on'/'off', 'true'/'false' and '1'/'0'.
:strong:`cache_path_pattern`
Specify cache path pattern.
:strong:`conf_dir`
List of configuration directories separated with the character conventionally
used by the operating system to separate search path components (as in PATH),
such as ':' for POSIX or ';' for Windows.
If also specified at command line then values from command line are
appended to this value.
:strong:`init_manifest`
Specify default initial manifest.
:strong:`inventory_dir`
Specify inventory directory.
:strong:`jobs`
Specify number of jobs for parallel processing. If -1 then the default,
number of CPU's in the system is used. If 0 then parallel processing in
jobs is disabled. If set to positive number then specified maximum
number of processes will be used.
:strong:`local_shell`
Shell command used for local execution.
:strong:`out_path`
Directory to save cdist output in.
:strong:`parallel`
Process hosts in parallel. If -1 then the default, number of CPU's in
the system is used. If 0 then parallel processing of hosts is disabled.
If set to positive number then specified maximum number of processes
will be used.
:strong:`remote_copy`
Command to use for remote copy (should behave like scp).
:strong:`remote_exec`
Command to use for remote execution (should behave like ssh).
:strong:`remote_out_path`
Directory to save cdist output in on the target host.
:strong:`remote_shell`
Shell command at remote host used for remote execution.
:strong:`save_output_streams`
Enable/disable saving output streams (enabled by default).
It recognizes boolean values from 'yes'/'no', 'on'/'off', 'true'/'false'
and '1'/'0'.
:strong:`timestamp`
Timestamp log messages with the current local date and time
in the format: YYYYMMDDHHMMSS.us.
:strong:`verbosity`
Set verbosity level. Valid values are:
'ERROR', 'WARNING', 'INFO', 'VERBOSE', 'DEBUG', 'TRACE' and 'OFF'.
FILES
-----
~/.cdist
Your personal cdist config directory. If exists it will be
automatically used.
~/.cdist/cache
Local cache directory.
~/.cdist/inventory
The home inventory directory. If ~/.cdist exists it will be used as
default inventory directory.
~/.cdist/preos
PreOS plugins directory, if existing.
cdist/conf
The distribution configuration directory. It contains official types and
explorers. This path is relative to cdist installation directory.
cdist/inventory
The distribution inventory directory.
This path is relative to cdist installation directory.
cdist/preos
The distribution PreOS plugins directory.
/etc/cdist.cfg
Global cdist configuration file, if exists.
~/.cdist.cfg or $XDG_CONFIG_HOME/cdist/cdist.cfg
Local cdist configuration file, if exists.
NOTES
-----
cdist detects if host is specified by IPv6 address. If so then remote_copy
command is executed with host address enclosed in square brackets
(see :strong:`scp`\ (1)).
EXAMPLES
--------
.. code-block:: sh
# Configure ikq05.ethz.ch with debug enabled
% cdist config -vvv ikq05.ethz.ch
# Configure hosts in parallel and use a different configuration directory
% cdist config -c ~/p/cdist-nutzung \
-p ikq02.ethz.ch ikq03.ethz.ch ikq04.ethz.ch
# Use custom remote exec / copy commands
% cdist config --remote-exec /path/to/my/remote/exec \
--remote-copy /path/to/my/remote/copy \
-p ikq02.ethz.ch ikq03.ethz.ch ikq04.ethz.ch
# Configure hosts read from file loadbalancers
% cdist config -f loadbalancers
# Configure hosts read from file web.hosts using 16 parallel jobs
% cdist config -j 16 -f web.hosts
# Display banner
cdist banner
# Show help
% cdist --help
# Show Version
% cdist --version
# Enter a shell that has access to emulated types
% cdist shell
% __git
usage: __git --source SOURCE [--state STATE] [--branch BRANCH]
[--group GROUP] [--owner OWNER] [--mode MODE] object_id
# Install ikq05.ethz.ch with debug enabled
% cdist install -vvv ikq05.ethz.ch
# List inventory content
% cdist inventory list -b
# List inventory for specified host localhost
% cdist inventory list -b localhost
# List inventory for specified tag loadbalancer
% cdist inventory list -b -t loadbalancer
# Add hosts to inventory
% cdist inventory add-host -b web1 web2 web3
# Delete hosts from file old-hosts from inventory
% cdist inventory del-host -b -f old-hosts
# Add tags to specified hosts
% cdist inventory add-tag -b -t europe,croatia,web,static web1 web2
# Add tag to all hosts in inventory
% cdist inventory add-tag -b -t vm
# Delete all tags from specified host
% cdist inventory del-tag -b -a localhost
# Delete tags read from stdin from hosts specified by file hosts
% cdist inventory del-tag -b -T - -f hosts
# Configure hosts from inventory with any of specified tags
% cdist config -b -t web dynamic
# Configure hosts from inventory with all specified tags
% cdist config -b -t -a web dynamic
# Configure all hosts from inventory db
$ cdist config -b -A
# Create default debian PreOS in debug mode
$ cdist preos debian /preos/preos-debian -vvvv -C \
-k ~/.ssh/id_rsa.pub -p /preos/pxe-debian
# Create ubuntu PreOS
$ cdist preos ubuntu /preos/preos-ubuntu -C \
-k ~/.ssh/id_rsa.pub -p /preos/pxe-ubuntu
# Create ubuntu PreOS on drive /dev/sdb
# and set root password to 'password'.
$ cdist preos ubuntu /mnt -B -C \
-k ~/.ssh/id_rsa.pub -D /dev/sdb \
-P password
ENVIRONMENT
-----------
TMPDIR, TEMP, TMP
Setup the base directory for the temporary directory.
See http://docs.python.org/py3k/library/tempfile.html for
more information. This is rather useful, if the standard
directory used does not allow executables.
CDIST_PATH
Colon delimited list of config directories.
CDIST_LOCAL_SHELL
Selects shell for local script execution, defaults to /bin/sh.
CDIST_REMOTE_SHELL
Selects shell for remote script execution, defaults to /bin/sh.
CDIST_OVERRIDE
Allow overwriting type parameters.
CDIST_ORDER_DEPENDENCY
Create dependencies based on the execution order.
Note that in version 6.2.0 semantic of this processing mode is
finally fixed and well defined.
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).
CDIST_INVENTORY_DIR
Use this directory as inventory directory.
CDIST_BETA
Enable beta functionality.
CDIST_CACHE_PATH_PATTERN
Custom cache path pattern.
CDIST_CONFIG_FILE
Custom configuration file.
EXIT STATUS
-----------
The following exit values shall be returned:
0 Successful completion.
1 One or more host configurations failed.
AUTHORS
-------
Originally written by Nico Schottelius <nico-cdist--@--schottelius.org>
and Steven Armstrong <steven-cdist--@--armstrong.cc>.
CAVEATS
-------
When operating in parallel, either by operating in parallel for each host
(-p/--parallel) or by parallel jobs within a host (-j/--jobs), and depending
on target SSH server and its configuration you may encounter connection drops.
This is controlled with sshd :strong:`MaxStartups` configuration options.
You may also encounter session open refusal. This happens with ssh multiplexing
when you reach maximum number of open sessions permitted per network
connection. In this case ssh will disable multiplexing.
This limit is controlled with sshd :strong:`MaxSessions` configuration
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 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 display a warning message. An example of such a case:
.. code-block:: sh
init manifest:
__a a
require="__e/e" __b b
require="__f/f" __c c
__e e
__f f
require="__c/c" __d d
__g g
__h h
type __g manifest:
require="__c/c __d/d" __a a
Warning message:
WARNING: cdisttesthost: Object __a/a already exists with requirements:
/usr/home/darko/ungleich/cdist/cdist/test/config/fixtures/manifest/init-deps-resolver /tmp/tmp.cdist.test.ozagkg54/local/759547ff4356de6e3d9e08522b0d0807/data/conf/type/__g/manifest: set()
/tmp/tmp.cdist.test.ozagkg54/local/759547ff4356de6e3d9e08522b0d0807/data/conf/type/__g/manifest: {'__c/c', '__d/d'}
Dependency resolver could not handle dependencies as expected.
COPYING
-------
Copyright \(C) 2011-2019 Nico Schottelius. Free use of this software is
granted under the terms of the GNU General Public License v3 or later (GPLv3+).

85
src/extra/manual/6.3.0/_sources/man7/cdist-type__acl.rst.txt Normal file
View file

@ -0,0 +1,85 @@
cdist-type__acl(7)
==================
NAME
----
cdist-type__acl - Set ACL entries
DESCRIPTION
-----------
Fully supported and tested on Linux (ext4 filesystem), partial support for FreeBSD.
See ``setfacl`` and ``acl`` manpages for more details.
REQUIRED MULTIPLE PARAMETERS
----------------------------
acl
Set ACL entry following ``getfacl`` output syntax.
BOOLEAN PARAMETERS
------------------
default
Set all ACL entries as default too.
Only directories can have default ACLs.
Setting default ACL in FreeBSD is currently not supported.
recursive
Make ``setfacl`` recursive (Linux only), but not ``getfacl`` in explorer.
remove
Remove undefined ACL entries.
``mask`` and ``other`` entries can't be removed, but only changed.
DEPRECATED PARAMETERS
---------------------
Parameters ``user``, ``group``, ``mask`` and ``other`` are deprecated and they
will be removed in future versions. Please use ``acl`` parameter instead.
EXAMPLES
--------
.. code-block:: sh
__acl /srv/project \
--default \
--recursive \
--remove \
--acl user:alice:rwx \
--acl user:bob:r-x \
--acl group:project-group:rwx \
--acl group:some-other-group:r-x \
--acl mask::r-x \
--acl other::r-x
# give Alice read-only access to subdir,
# but don't allow her to see parent content.
__acl /srv/project2 \
--remove \
--acl default:group:secret-project:rwx \
--acl group:secret-project:rwx \
--acl user:alice:--x
__acl /srv/project2/subdir \
--default \
--remove \
--acl group:secret-project:rwx \
--acl user:alice:r-x
AUTHORS
-------
Ander Punnar <ander-at-kvlt-dot-ee>
COPYING
-------
Copyright \(C) 2018 Ander Punnar. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

46
src/extra/manual/6.3.0/_sources/man7/cdist-type__apt_default_release.rst.txt Normal file
View file

@ -0,0 +1,46 @@
cdist-type__apt_default_release(7)
==================================
NAME
----
cdist-type__apt_default_release - Configure the default release for apt
DESCRIPTION
-----------
Configure the default release for apt, using the APT::Default-Release
configuration value.
REQUIRED PARAMETERS
-------------------
release
The value to set APT::Default-Release to.
This can contain release name, codename or release version. Examples:
'stable', 'testing', 'unstable', 'stretch', 'buster', '4.0', '5.0*'.
OPTIONAL PARAMETERS
-------------------
None.
EXAMPLES
--------
.. code-block:: sh
__apt_default_release --release stretch
AUTHORS
-------
Matthijs Kooijman <matthijs--@--stdin.nl>
COPYING
-------
Copyright \(C) 2017 Matthijs Kooijman. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

72
src/extra/manual/6.3.0/_sources/man7/cdist-type__apt_key.rst.txt Normal file
View file

@ -0,0 +1,72 @@
cdist-type__apt_key(7)
======================
NAME
----
cdist-type__apt_key - Manage the list of keys used by apt
DESCRIPTION
-----------
Manages the list of keys used by apt to authenticate packages.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
state
'present' or 'absent'. Defaults to 'present'
keyid
the id of the key to add. Defaults to __object_id
keyserver
the keyserver from which to fetch the key. If omitted the default set
in ./parameter/default/keyserver is used.
keydir
key save location, defaults to ``/etc/apt/trusted.pgp.d``
uri
the URI from which to download the key
EXAMPLES
--------
.. code-block:: sh
# Add Ubuntu Archive Automatic Signing Key
__apt_key 437D05B5
# Same thing
__apt_key 437D05B5 --state present
# Get rid of it
__apt_key 437D05B5 --state absent
# same thing with human readable name and explicit keyid
__apt_key UbuntuArchiveKey --keyid 437D05B5
# same thing with other keyserver
__apt_key UbuntuArchiveKey --keyid 437D05B5 --keyserver keyserver.ubuntu.com
# download key from the internet
__apt_key rabbitmq \
--uri http://www.rabbitmq.com/rabbitmq-signing-key-public.asc
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
Ander Punnar <ander-at-kvlt-dot-ee>
COPYING
-------
Copyright \(C) 2011-2019 Steven Armstrong and Ander Punnar. You can
redistribute it and/or modify it under the terms of the GNU General Public
License as published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

51
src/extra/manual/6.3.0/_sources/man7/cdist-type__apt_key_uri.rst.txt Normal file
View file

@ -0,0 +1,51 @@
cdist-type__apt_key_uri(7)
==========================
NAME
----
cdist-type__apt_key_uri - Add apt key from uri
DESCRIPTION
-----------
Download a key from an uri and add it to the apt keyring.
REQUIRED PARAMETERS
-------------------
uri
the uri from which to download the key
OPTIONAL PARAMETERS
-------------------
state
'present' or 'absent', defaults to 'present'
name
a name for this key, used when testing if it is already installed.
Defaults to __object_id
EXAMPLES
--------
.. code-block:: sh
__apt_key_uri rabbitmq \
--name 'RabbitMQ Release Signing Key <info@rabbitmq.com>' \
--uri http://www.rabbitmq.com/rabbitmq-signing-key-public.asc \
--state present
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2011-2014 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

47
src/extra/manual/6.3.0/_sources/man7/cdist-type__apt_mark.rst.txt Normal file
View file

@ -0,0 +1,47 @@
cdist-type__apt_mark(7)
=======================
NAME
----
cdist-type__apt_mark - set package state as 'hold' or 'unhold'
DESCRIPTION
-----------
See apt-mark(8) for details.
REQUIRED PARAMETERS
-------------------
state
Either "hold" or "unhold".
OPTIONAL PARAMETERS
-------------------
name
If supplied, use the name and not the object id as the package name.
EXAMPLES
--------
.. code-block:: sh
# hold package
__apt_mark quagga --state hold
# unhold package
__apt_mark quagga --state unhold
AUTHORS
-------
Ander Punnar <cdist--@--kvlt.ee>
COPYING
-------
Copyright \(C) 2016 Ander Punnar. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

42
src/extra/manual/6.3.0/_sources/man7/cdist-type__apt_norecommends.rst.txt Normal file
View file

@ -0,0 +1,42 @@
cdist-type__apt_norecommends(7)
===============================
NAME
----
cdist-type__apt_norecommends - Configure apt to not install recommended packages
DESCRIPTION
-----------
Configure apt to not install any recommended or suggested packages.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
None.
EXAMPLES
--------
.. code-block:: sh
__apt_norecommends
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2014 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

50
src/extra/manual/6.3.0/_sources/man7/cdist-type__apt_ppa.rst.txt Normal file
View file

@ -0,0 +1,50 @@
cdist-type__apt_ppa(7)
======================
NAME
----
cdist-type__apt_ppa - Manage ppa repositories
DESCRIPTION
-----------
This cdist type allows manage ubuntu ppa repositories.
REQUIRED PARAMETERS
-------------------
state
The state the ppa should be in, either 'present' or 'absent'.
Defaults to 'present'
OPTIONAL PARAMETERS
-------------------
None.
EXAMPLES
--------
.. code-block:: sh
# Enable a ppa repository
__apt_ppa ppa:sans-intern/missing-bits
# same as
__apt_ppa ppa:sans-intern/missing-bits --state present
# Disable a ppa repository
__apt_ppa ppa:sans-intern/missing-bits --state absent
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2011-2014 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

70
src/extra/manual/6.3.0/_sources/man7/cdist-type__apt_source.rst.txt Normal file
View file

@ -0,0 +1,70 @@
cdist-type__apt_source(7)
=========================
NAME
----
cdist-type__apt_source - Manage apt sources
DESCRIPTION
-----------
This cdist type allows you to manage apt sources. It invokes index update
internally when needed so call of index updating type is not needed.
REQUIRED PARAMETERS
-------------------
uri
the uri to the apt repository
OPTIONAL PARAMETERS
-------------------
arch
set this if you need to force and specific arch (ubuntu specific)
state
'present' or 'absent', defaults to 'present'
distribution
the distribution codename to use. Defaults to DISTRIB_CODENAME from
the targets /etc/lsb-release
component
space delimited list of components to enable. Defaults to an empty string.
BOOLEAN PARAMETERS
------------------
include-src
include deb-src entries
EXAMPLES
--------
.. code-block:: sh
__apt_source rabbitmq \
--uri http://www.rabbitmq.com/debian/ \
--distribution testing \
--component main \
--include-src \
--state present
__apt_source canonical_partner \
--uri http://archive.canonical.com/ \
--component partner --state present
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2011-2018 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

41
src/extra/manual/6.3.0/_sources/man7/cdist-type__apt_update_index.rst.txt Normal file
View file

@ -0,0 +1,41 @@
cdist-type__apt_update_index(7)
===============================
NAME
----
cdist-type__apt_update_index - Update apt's package index
DESCRIPTION
-----------
This cdist type runs apt-get update whenever any apt sources have changed.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
None.
EXAMPLES
--------
.. code-block:: sh
__apt_update_index
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2011 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

82
src/extra/manual/6.3.0/_sources/man7/cdist-type__block.rst.txt Normal file
View file

@ -0,0 +1,82 @@
cdist-type__block(7)
====================
NAME
----
cdist-type__block - Manage blocks of text in files
DESCRIPTION
-----------
Manage a block of text in an existing file.
The block is identified using the prefix and suffix parameters.
Everything between prefix and suffix is considered to be a managed block
of text.
REQUIRED PARAMETERS
-------------------
text
the text to manage.
If text is '-' (dash), take what was written to stdin as the text.
OPTIONAL PARAMETERS
-------------------
file
the file in which to manage the text block.
Defaults to object_id.
prefix
the prefix to add before the text.
Defaults to #cdist:__block/$__object_id
suffix
the suffix to add after the text.
Defaults to #/cdist:__block/$__object_id
state
'present' or 'absent', defaults to 'present'
MESSAGES
--------
add
block was added
update
block was updated/changed
remove
block was removed
EXAMPLES
--------
.. code-block:: sh
# text from argument
__block /path/to/file \
--prefix '#start' \
--suffix '#end' \
--text 'some\nblock of\ntext'
# text from stdin
__block some-id \
--file /path/to/file \
--text - << DONE
here some block
of text
DONE
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2013 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

78
src/extra/manual/6.3.0/_sources/man7/cdist-type__ccollect_source.rst.txt Normal file
View file

@ -0,0 +1,78 @@
cdist-type__ccollect_source(7)
==============================
NAME
----
cdist-type__ccollect_source - Manage ccollect sources
DESCRIPTION
-----------
This cdist type allows you to create or delete ccollect sources.
REQUIRED PARAMETERS
-------------------
source
The source from which to backup
destination
The destination directory
OPTIONAL PARAMETERS
-------------------
state
'present' or 'absent', defaults to 'present'
ccollectconf
The CCOLLECT_CONF directory. Defaults to /etc/ccollect.
OPTIONAL MULTIPLE PARAMETERS
----------------------------
exclude
Paths to exclude of backup
BOOLEAN PARAMETERS
------------------
verbose
Whether to report backup verbosely
create-destination
Create the directory specified in the destination parameter on the remote host
EXAMPLES
--------
.. code-block:: sh
__ccollect_source doc.ungleich.ch \
--source doc.ungleich.ch:/ \
--destination /backup/doc.ungleich.ch \
--exclude '/proc/*' --exclude '/sys/*' \
--verbose
__ccollect_source doc.ungleich.ch \
--source doc.ungleich.ch:/ \
--destination /backup/doc.ungleich.ch \
--exclude '/proc/*' --exclude '/sys/*' \
--verbose \
--create-destination
SEE ALSO
--------
:strong:`ccollect`\ (1)
AUTHORS
-------
Nico Schottelius <nico-cdist--@--schottelius.org>
COPYING
-------
Copyright \(C) 2014 Nico Schottelius. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

63
src/extra/manual/6.3.0/_sources/man7/cdist-type__cdist.rst.txt Normal file
View file

@ -0,0 +1,63 @@
cdist-type__cdist(7)
====================
NAME
----
cdist-type__cdist - Manage cdist installations
DESCRIPTION
-----------
This cdist type allows you to easily setup cdist
on another box, to allow the other box to configure
systems.
This type is *NOT* required by target hosts.
It is only helpful to build FROM which you configure
other hosts.
This type will use git to clone
REQUIRED PARAMETERS
-------------------
OPTIONAL PARAMETERS
-------------------
username
Select the user to create for the cdist installation.
Defaults to "cdist".
source
Select the source from which to clone cdist from.
Defaults to "git@code.ungleich.ch:ungleich-public/cdist.git".
branch
Select the branch to checkout from.
Defaults to "master".
EXAMPLES
--------
.. code-block:: sh
# Install cdist for user cdist in her home as subfolder cdist
__cdist /home/cdist/cdist
# Use alternative source
__cdist --source "git@code.ungleich.ch:ungleich-public/cdist.git" /home/cdist/cdist
AUTHORS
-------
Nico Schottelius <nico-cdist--@--schottelius.org>
COPYING
-------
Copyright \(C) 2013 Nico Schottelius. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

55
src/extra/manual/6.3.0/_sources/man7/cdist-type__cdistmarker.rst.txt Normal file
View file

@ -0,0 +1,55 @@
cdist-type__cdistmarker(7)
==========================
NAME
----
cdist-type__cdistmarker - Add a timestamped cdist marker.
DESCRIPTION
-----------
This type is used to add a common marker file which indicates that a given
machine is being managed by cdist. The contents of this file consist of a
timestamp, which can be used to determine the most recent time at which cdist
was run against the machine in question.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
destination
The path and filename of the marker.
Default: /etc/cdist-configured
format
The format of the timestamp. This is passed directly to system 'date'.
Default: -u
EXAMPLES
--------
.. code-block:: sh
# Creates the marker as normal.
__cdistmarker
# Creates the marker differently.
__cdistmarker --destination /tmp/cdist_marker --format '+%s'
AUTHORS
-------
Daniel Maher <phrawzty+cdist--@--gmail.com>
COPYING
-------
Copyright \(C) 2011 Daniel Maher. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

52
src/extra/manual/6.3.0/_sources/man7/cdist-type__check_messages.rst.txt Normal file
View file

@ -0,0 +1,52 @@
cdist-type__check_messages(7)
=============================
NAME
----
cdist-type__check_messages - Check messages for pattern and execute command on match.
DESCRIPTION
-----------
Check messages for pattern and execute command on match.
This type is useful if you chain together multiple related types using
dependencies and want to restart service if at least one type changes
something.
For more information about messages see `cdist messaging <cdist-messaging.html>`_.
For more information about dependencies and execution order see
`cdist manifest <cdist-manifest.html#dependencies>`_ documentation.
REQUIRED PARAMETERS
-------------------
pattern
Extended regular expression pattern for search (passed to ``grep -E``).
execute
Command to execute on pattern match.
EXAMPLES
--------
.. code-block:: sh
__check_messages munin \
--pattern '^__(file|link|line)/etc/munin/' \
--execute 'service munin-node restart'
AUTHORS
-------
Ander Punnar <ander-at-kvlt-dot-ee>
COPYING
-------
Copyright \(C) 2019 Ander Punnar. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

55
src/extra/manual/6.3.0/_sources/man7/cdist-type__chroot_mount.rst.txt Normal file
View file

@ -0,0 +1,55 @@
cdist-type__chroot_mount(7)
===========================
NAME
----
cdist-type__chroot_mount - mount a chroot
DESCRIPTION
-----------
Mount and prepare a chroot for running commands within it.
REQUIRED PARAMETERS
-------------------
None
OPTIONAL PARAMETERS
-------------------
manage-resolv-conf
manage /etc/resolv.conf inside the chroot.
Use the value of this parameter as the suffix to save a copy
of the current /etc/resolv.conf to /etc/resolv.conf.$suffix.
This is used by the __chroot_umount type to restore the initial
file content when unmounting the chroot.
BOOLEAN PARAMETERS
------------------
None.
EXAMPLES
--------
.. code-block:: sh
__chroot_mount /path/to/chroot
__chroot_mount /path/to/chroot \
--manage-resolv-conf "some-known-string"
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2012-2017 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

60
src/extra/manual/6.3.0/_sources/man7/cdist-type__chroot_umount.rst.txt Normal file
View file

@ -0,0 +1,60 @@
cdist-type__chroot_umount(7)
============================
NAME
----
cdist-type__chroot_umount - unmount a chroot mounted by __chroot_mount
DESCRIPTION
-----------
Undo what __chroot_mount did.
REQUIRED PARAMETERS
-------------------
None
OPTIONAL PARAMETERS
-------------------
manage-resolv-conf
manage /etc/resolv.conf inside the chroot.
Use the value of this parameter as the suffix to find the backup file
that was saved by the __chroot_mount.
This is used by the to restore the initial file content when unmounting
the chroot.
BOOLEAN PARAMETERS
------------------
None.
EXAMPLES
--------
.. code-block:: sh
__chroot_umount /path/to/chroot
__chroot_umount /path/to/chroot \
--manage-resolv-conf "some-known-string"
SEE ALSO
--------
:strong:`cdist-type__chroot_mount`\ (7)
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2012-2017 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

60
src/extra/manual/6.3.0/_sources/man7/cdist-type__clean_path.rst.txt Normal file
View file

@ -0,0 +1,60 @@
cdist-type__clean_path(7)
=========================
NAME
----
cdist-type__clean_path - Remove files and directories which match the pattern.
DESCRIPTION
-----------
Remove files and directories which match the pattern.
Provided path (as __object_id) must be a directory.
Patterns are passed to ``find``'s ``-regex`` - see ``find(1)`` for more details.
Look up of files and directories is non-recursive (``-maxdepth 1``).
Parent directory is excluded (``-mindepth 1``).
This type is not POSIX compatible (sorry, Solaris users).
REQUIRED PARAMETERS
-------------------
pattern
Pattern of files which are removed from path.
OPTIONAL PARAMETERS
-------------------
exclude
Pattern of files which are excluded from removal.
onchange
The code to run if files or directories were removed.
EXAMPLES
--------
.. code-block:: sh
__clean_path /etc/apache2/conf-enabled \
--pattern '.+' \
--exclude '.+\(charset\.conf\|security\.conf\)' \
--onchange 'service apache2 restart'
AUTHORS
-------
Ander Punnar <ander-at-kvlt-dot-ee>
COPYING
-------
Copyright \(C) 2019 Ander Punnar. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

64
src/extra/manual/6.3.0/_sources/man7/cdist-type__config_file.rst.txt Normal file
View file

@ -0,0 +1,64 @@
cdist-type__config_file(7)
==========================
NAME
----
cdist-type__config_file - _Manages config files
DESCRIPTION
-----------
Deploy config files using the file type.
Run the given code if the files changes.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
group
see cdist-type__file
mode
see cdist-type__file
onchange
the code to run if the file changes
owner
see cdist-type__file
source
Path to the config file.
If source is '-' (dash), take what was written to stdin as the config file content.
state
see cdist-type__file
EXAMPLES
--------
.. code-block:: sh
__config_file /etc/consul/conf.d/watch_foo.json \
--owner root --group consul --mode 640 \
--source "$__type/files/watch_foo.json" \
--state present \
--onchange 'service consul status >/dev/null && service consul reload || true'
SEE ALSO
--------
:strong:`cdist-type__file`\ (7)
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2015 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

75
src/extra/manual/6.3.0/_sources/man7/cdist-type__consul.rst.txt Normal file
View file

@ -0,0 +1,75 @@
cdist-type__consul(7)
=====================
NAME
----
cdist-type__consul - Install consul
DESCRIPTION
-----------
Downloads and installs the consul binary from https://dl.bintray.com/mitchellh/consul.
Note that the consul binary is downloaded on the server (the machine running
cdist) and then deployed to the target host using the __file type unless --direct
parameter is used.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
state
either 'present' or 'absent'. Defaults to 'present'
version
which version of consul to install. See ./files/versions for a list of
supported versions. Defaults to the latest known version.
BOOLEAN PARAMETERS
------------------
direct
Download and deploy consul binary directly on the target machine.
MESSAGES
--------
If consul binary is created using __staged_file then underlaying __file type messages are emitted.
If consul binary is created by direct method then the following messages are emitted:
/usr/local/bin/consul created
consul binary was created
EXAMPLES
--------
.. code-block:: sh
# just install using defaults
__consul
# install by downloading consul binary directly on the target machine
__consul --direct
# specific version
__consul \
--version 0.4.1
AUTHORS
-------
| Steven Armstrong <steven-cdist--@--armstrong.cc>
| Darko Poljak <darko.poljak--@--gmail.com>
COPYING
-------
Copyright \(C) 2015 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

181
src/extra/manual/6.3.0/_sources/man7/cdist-type__consul_agent.rst.txt Normal file
View file

@ -0,0 +1,181 @@
cdist-type__consul_agent(7)
===========================
NAME
----
cdist-type__consul_agent - Manage the consul agent
DESCRIPTION
-----------
Configure and manage the consul agent.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
acl-datacenter
only used by servers. This designates the datacenter which is authoritative
for ACL information.
acl-default-policy
either "allow" or "deny"; defaults to "allow". The default policy controls the
behavior of a token when there is no matching rule.
acl-down-policy
either "allow", "deny" or "extend-cache"; "extend-cache" is the default.
acl-master-token
only used for servers in the acl_datacenter. This token will be created with
management-level permissions if it does not exist. It allows operators to
bootstrap the ACL system with a token ID that is well-known.
acl-token
when provided, the agent will use this token when making requests to the
Consul servers.
acl-ttl
used to control Time-To-Live caching of ACLs.
bind-addr
sets the bind address for cluster communication
bootstrap-expect
sets server to expect bootstrap mode
ca-file-source
path to a PEM encoded certificate authority file which will be uploaded and
configure using the ca_file config option.
cert-file-source
path to a PEM encoded certificate file which will be uploaded and
configure using the cert_file config option.
client-addr
sets the address to bind for client access
datacenter
datacenter of the agent
encrypt
provides the gossip encryption key
group
the primary group for the agent
json-config
path to a partial json config file without leading { and trailing }.
If json-config is '-' (dash), take what was written to stdin as the file content.
key-file-source
path to a PEM encoded private key file which will be uploaded and
configure using the key_file config option.
node-name
name of this node. Must be unique in the cluster
retry-join
address to attempt joining every retry_interval until at least one join works.
Can be specified multiple times.
user
the user to run the agent as
state
if the agent is 'present' or 'absent'. Defaults to 'present'.
Currently state=absent is not working due to some dependency issues.
BOOLEAN PARAMETERS
------------------
disable-remote-exec
disables support for remote execution. When set to true, the agent will ignore any incoming remote exec requests.
disable-update-check
disables automatic checking for security bulletins and new version releases
leave-on-terminate
gracefully leave cluster on SIGTERM
rejoin-after-leave
rejoin the cluster using the previous state after leaving
server
used to control if an agent is in server or client mode
enable-syslog
enables logging to syslog
verify-incoming
enforce the use of TLS and verify a client's authenticity on incoming connections
verify-outgoing
enforce the use of TLS and verify the peers authenticity on outgoing connections
EXAMPLES
--------
.. code-block:: sh
# configure as server, bootstrap and rejoin
hostname="$(cat "$__global/explorer/hostname")"
__consul_agent \
--datacenter dc1 \
--node-name "${hostname%%.*}" \
--disable-update-check \
--server \
--rejoin-after-leave \
--bootstrap-expect 3 \
--retry-join consul-01 \
--retry-join consul-02 \
--retry-join consul-03
# configure as server, bootstrap and rejoin with ssl support
hostname="$(cat "$__global/explorer/hostname")"
__consul_agent \
--datacenter dc1 \
--node-name "${hostname%%.*}" \
--disable-update-check \
--server \
--rejoin-after-leave \
--bootstrap-expect 3 \
--retry-join consul-01 \
--retry-join consul-02 \
--retry-join consul-03 \
--ca-file-source /path/to/ca.pem \
--cert-file-source /path/to/cert.pem \
--key-file-source /path/to/key.pem \
--verify-incoming \
--verify-outgoing
# configure as client and try joining existing cluster
__consul_agent \
--datacenter dc1 \
--node-name "${hostname%%.*}" \
--disable-update-check \
--retry-join consul-01 \
--retry-join consul-02 \
--retry-join consul-03
SEE ALSO
--------
consul documentation at: <http://www.consul.io/docs/agent/options.html>.
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2015 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

102
src/extra/manual/6.3.0/_sources/man7/cdist-type__consul_check.rst.txt Normal file
View file

@ -0,0 +1,102 @@
cdist-type__consul_check(7)
=============================
NAME
----
cdist-type__consul_check - Manages consul checks
DESCRIPTION
-----------
Generate and deploy check definitions for a consul agent.
See http://www.consul.io/docs/agent/checks.html for parameter documentation.
Use either script together with interval, or use ttl.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
docker-container-id
the id of the docker container to run
http
the url to check
id
The id of this check.
interval
the interval in which the check should run
name
The name of this check. Defaults to __object_id
notes
human readable description
script
the shell command to run
service-id
the id of the service this check is bound to
shell
the shell to run inside the docker container
state
if this check is 'present' or 'absent'. Defaults to 'present'.
status
specify the initial state of this health check
tcp
the host and port to check
timeout
after how long to timeout checks which take to long
token
ACL token to use for interacting with the catalog
ttl
how long a TTL check is considered healthy without being updated through the
HTTP interface
EXAMPLES
--------
.. code-block:: sh
__consul_check redis \
--script /usr/local/bin/check_redis.py \
--interval 10s
__consul_check some-object-id \
--id web-app \
--name "Web App Status" \
--notes "Web app does a curl internally every 10 seconds" \
--ttl 30s
SEE ALSO
--------
:strong:`cdist-type__consul_agent`\ (7)
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2015-2016 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

42
src/extra/manual/6.3.0/_sources/man7/cdist-type__consul_reload.rst.txt Normal file
View file

@ -0,0 +1,42 @@
cdist-type__consul_reload(7)
============================
NAME
----
cdist-type__consul_reload - Reload consul
DESCRIPTION
-----------
Reload consul after configuration changes.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
None.
EXAMPLES
--------
.. code-block:: sh
__consul_reload
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2015 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

85
src/extra/manual/6.3.0/_sources/man7/cdist-type__consul_service.rst.txt Normal file
View file

@ -0,0 +1,85 @@
cdist-type__consul_service(7)
=============================
NAME
----
cdist-type__consul_service - Manages consul services
DESCRIPTION
-----------
Generate and deploy service definitions for a consul agent.
See http://www.consul.io/docs/agent/services.html for parameter documentation.
Use either script together with interval, or use ttl.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
check-interval
the interval in which the script given with --check-script should be run
check-http
the URL to check for HTTP 200-ish status every --check-interval
check-script
the shell command to run every --check-interval
check-ttl
how long a service is considered healthy without being updated through the
HTTP interfave
id
Defaults to --name
name
The name of this service. Defaults to __object_id
port
the port at which this service can be reached
state
if this service is 'present' or 'absent'. Defaults to 'present'.
tag
a tag to add to this service. Can be specified multiple times.
EXAMPLES
--------
.. code-block:: sh
__consul_service redis \
--tag master \
--tag production \
--port 8000 \
--check-script /usr/local/bin/check_redis.py \
--check-interval 10s
__consul_service webapp \
--port 80 \
--check-ttl 10s
SEE ALSO
--------
:strong:`cdist-type__consul_agent`\ (7)
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2015 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

141
src/extra/manual/6.3.0/_sources/man7/cdist-type__consul_template.rst.txt Normal file
View file

@ -0,0 +1,141 @@
cdist-type__consul_template(7)
==============================
NAME
----
cdist-type__consul_template - Manage the consul-template service
DESCRIPTION
-----------
Downloads and installs the consul-template binary from
https://github.com/hashicorp/consul-template/releases/download/.
Generates a global config file and creates directory for per template config files.
Note that the consul-template binary is downloaded on the server (the machine running
cdist) and then deployed to the target host using the __file type.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
auth-username
specify a username for basic authentication.
auth-password
specify a password for basic authentication.
batch-size
the size of the batch when polling multiple dependencies.
consul
the location of the Consul instance to query (may be an IP address or FQDN) with port.
Defaults to 'localhost:8500'.
log-level
The log level for output. This applies to the stdout/stderr logging as well
as syslog logging (if enabled). Valid values are "debug", "info", "warn",
and "err". The default value is "warn".
max-stale
the maximum staleness of a query. If specified, Consul will distribute work among all
servers instead of just the leader.
retry
the amount of time to wait if Consul returns an error when communicating
with the API.
state
either 'present' or 'absent'. Defaults to 'present'
ssl-cert
Path to an SSL client certificate to use to authenticate to the consul server.
Useful if the consul server "verify_incoming" option is set.
ssl-ca-cert
Path to a CA certificate file, containing one or more CA certificates to
use to validate the certificate sent by the consul server to us. This is a
handy alternative to setting --ssl-no-verify if you are using your own CA.
syslog-facility
The facility to use when sending to syslog. This requires the use of --syslog.
The default value is LOCAL0.
token
the Consul API token.
vault-address
the location of the Vault instance to query (may be an IP address or FQDN) with port.
vault-token
the Vault API token.
vault-ssl-cert
Path to an SSL client certificate to use to authenticate to the vault server.
vault-ssl-ca-cert
Path to a CA certificate file, containing one or more CA certificates to
use to validate the certificate sent by the vault server to us.
version
which version of consul-template to install. See ./files/versions for a list of
supported versions. Defaults to the latest known version.
wait
the minimum(:maximum) to wait before rendering a new template to disk and
triggering a command, separated by a colon (:). If the optional maximum
value is omitted, it is assumed to be 4x the required minimum value.
BOOLEAN PARAMETERS
------------------
ssl
use HTTPS while talking to Consul. Requires the Consul server to be configured to serve secure connections.
ssl-no-verify
ignore certificate warnings. Only used if ssl is enabled.
syslog
Send log output to syslog (in addition to stdout and stderr).
vault-ssl
use HTTPS while talking to Vault. Requires the Vault server to be configured to serve secure connections.
vault-ssl-no-verify
ignore certificate warnings. Only used if vault is enabled.
EXAMPLES
--------
.. code-block:: sh
__consul_template \
--consul consul.service.consul:8500 \
--retry 30s
# specific version
__consul_template \
--version 0.6.5 \
--retry 30s
SEE ALSO
--------
consul documentation at: <https://github.com/hashicorp/consul-template>.
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2015 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

84
src/extra/manual/6.3.0/_sources/man7/cdist-type__consul_template_template.rst.txt Normal file
View file

@ -0,0 +1,84 @@
cdist-type__consul_template_template(7)
=======================================
NAME
----
cdist-type__consul_template_template - Manage consul-template templates
DESCRIPTION
-----------
Generate and deploy template definitions for a consul-template.
See https://github.com/hashicorp/consul-template#examples for documentation.
Templates are written in the Go template format.
Either the --source or the --source-file parameter must be given.
REQUIRED PARAMETERS
-------------------
destination
the destination where the generated file should go.
OPTIONAL PARAMETERS
-------------------
command
an optional command to run after rendering the template to its destination.
source
path to the template source. Conflicts --source-file.
source-file
path to a local file which is uploaded using the __file type and configured
as the source.
If source is '-' (dash), take what was written to stdin as the file content.
Conflicts --source.
state
if this template is 'present' or 'absent'. Defaults to 'present'.
wait
The `minimum(:maximum)` time to wait before rendering a new template to
disk and triggering a command, separated by a colon (`:`). If the optional
maximum value is omitted, it is assumed to be 4x the required minimum value.
This is a numeric time with a unit suffix ("5s"). There is no default value.
The wait value for a template takes precedence over any globally-configured
wait.
EXAMPLES
--------
.. code-block:: sh
# configure template on the target
__consul_template_template nginx \
--source /etc/my-consul-templates/nginx.ctmpl \
--destination /etc/nginx/nginx.conf \
--command 'service nginx restart'
# upload a local file to the target and configure it
__consul_template_template nginx \
--wait '2s:6s' \
--source-file "$__manifest/files/nginx.ctmpl" \
--destination /etc/nginx/nginx.conf \
--command 'service nginx restart'
SEE ALSO
--------
:strong:`cdist-type__consul_template`\ (7), :strong:`cdist-type__consul_template_config`\ (7)
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2015-2016 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

73
src/extra/manual/6.3.0/_sources/man7/cdist-type__consul_watch_checks.rst.txt Normal file
View file

@ -0,0 +1,73 @@
cdist-type__consul_watch_checks(7)
==================================
NAME
----
cdist-type__consul_watch_checks - Manages consul checks watches
DESCRIPTION
-----------
Generate and deploy watch definitions of type 'checks' for a consul agent.
See http://www.consul.io/docs/agent/watches.html for parameter documentation.
REQUIRED PARAMETERS
-------------------
handler
the handler to invoke when the data view updates
OPTIONAL PARAMETERS
-------------------
datacenter
can be provided to override the agent's default datacenter
filter-service
filter to a specific service. Conflicts with --filter-state.
filter-state
filter to a specific state. Conflicts with --filter-service.
state
if this watch is 'present' or 'absent'. Defaults to 'present'.
token
can be provided to override the agent's default ACL token
EXAMPLES
--------
.. code-block:: sh
__consul_watch_checks some-id \
--handler /usr/bin/my-handler.sh
__consul_watch_checks some-id \
--filter-service consul \
--handler /usr/bin/my-handler.sh
__consul_watch_checks some-id \
--filter-state passing \
--handler /usr/bin/my-handler.sh
SEE ALSO
--------
:strong:`cdist-type__consul_agent`\ (7)
consul documentation at: <http://www.consul.io/docs/agent/watches.html>.
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2015 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

66
src/extra/manual/6.3.0/_sources/man7/cdist-type__consul_watch_event.rst.txt Normal file
View file

@ -0,0 +1,66 @@
cdist-type__consul_watch_event(7)
=================================
NAME
----
cdist-type__consul_watch_event - Manages consul event watches
DESCRIPTION
-----------
Generate and deploy watch definitions of type 'event' for a consul agent.
See http://www.consul.io/docs/agent/watches.html for parameter documentation.
REQUIRED PARAMETERS
-------------------
handler
the handler to invoke when the data view updates
OPTIONAL PARAMETERS
-------------------
datacenter
can be provided to override the agent's default datacenter
name
restrict the watch to only events with the given name
state
if this watch is 'present' or 'absent'. Defaults to 'present'.
token
can be provided to override the agent's default ACL token
EXAMPLES
--------
.. code-block:: sh
__consul_watch_event some-id \
--handler /usr/bin/my-handler.sh
__consul_watch_event some-id \
--name web-deploy \
--handler /usr/bin/my-handler.sh
SEE ALSO
--------
:strong:`cdist-type__consul_agent`\ (7)
consul documentation at: <http://www.consul.io/docs/agent/watches.html>.
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2015 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

63
src/extra/manual/6.3.0/_sources/man7/cdist-type__consul_watch_key.rst.txt Normal file
View file

@ -0,0 +1,63 @@
cdist-type__consul_watch_key(7)
===============================
NAME
----
cdist-type__consul_watch_key - Manages consul key watches
DESCRIPTION
-----------
Generate and deploy watch definitions of type 'key' for a consul agent.
See http://www.consul.io/docs/agent/watches.html for parameter documentation.
REQUIRED PARAMETERS
-------------------
handler
the handler to invoke when the data view updates
key
the key to watch for changes
OPTIONAL PARAMETERS
-------------------
datacenter
can be provided to override the agent's default datacenter
state
if this watch is 'present' or 'absent'. Defaults to 'present'.
token
can be provided to override the agent's default ACL token
EXAMPLES
--------
.. code-block:: sh
__consul_watch_key some-id \
--key foo/bar/baz \
--handler /usr/bin/my-key-handler.sh
SEE ALSO
--------
:strong:`cdist-type__consul_agent`\ (7)
consul documentation at: <http://www.consul.io/docs/agent/watches.html>.
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2015 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

63
src/extra/manual/6.3.0/_sources/man7/cdist-type__consul_watch_keyprefix.rst.txt Normal file
View file

@ -0,0 +1,63 @@
cdist-type__consul_watch_keyprefix(7)
=====================================
NAME
----
cdist-type__consul_watch_keyprefix - Manages consul keyprefix watches
DESCRIPTION
-----------
Generate and deploy watch definitions of type 'keyprefix' for a consul agent.
See http://www.consul.io/docs/agent/watches.html for parameter documentation.
REQUIRED PARAMETERS
-------------------
handler
the handler to invoke when the data view updates
prefix
the prefix of keys to watch for changes
OPTIONAL PARAMETERS
-------------------
datacenter
can be provided to override the agent's default datacenter
state
if this watch is 'present' or 'absent'. Defaults to 'present'.
token
can be provided to override the agent's default ACL token
EXAMPLES
--------
.. code-block:: sh
__consul_watch_keyprefix some-id \
--prefix foo/ \
--handler /usr/bin/my-prefix-handler.sh
SEE ALSO
--------
:strong:`cdist-type__consul_agent`\ (7)
consul documentation at: <http://www.consul.io/docs/agent/watches.html>.
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2015 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

59
src/extra/manual/6.3.0/_sources/man7/cdist-type__consul_watch_nodes.rst.txt Normal file
View file

@ -0,0 +1,59 @@
cdist-type__consul_watch_nodes(7)
=================================
NAME
----
cdist-type__consul_watch_nodes - Manages consul nodes watches
DESCRIPTION
-----------
Generate and deploy watch definitions of type 'nodes' for a consul agent.
See http://www.consul.io/docs/agent/watches.html for parameter documentation.
REQUIRED PARAMETERS
-------------------
handler
the handler to invoke when the data view updates
OPTIONAL PARAMETERS
-------------------
datacenter
can be provided to override the agent's default datacenter
state
if this watch is 'present' or 'absent'. Defaults to 'present'.
token
can be provided to override the agent's default ACL token
EXAMPLES
--------
.. code-block:: sh
__consul_watch_nodes some-id \
--handler /usr/bin/my-key-handler.sh
SEE ALSO
--------
:strong:`cdist-type__consul_agent`\ (7)
consul documentation at: <http://www.consul.io/docs/agent/watches.html>.
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2015 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

83
src/extra/manual/6.3.0/_sources/man7/cdist-type__consul_watch_service.rst.txt Normal file
View file

@ -0,0 +1,83 @@
cdist-type__consul_watch_service(7)
===================================
NAME
----
cdist-type__consul_watch_service - Manages consul service watches
DESCRIPTION
-----------
Generate and deploy watch definitions of type 'service' for a consul agent.
See http://www.consul.io/docs/agent/watches.html for parameter documentation.
REQUIRED PARAMETERS
-------------------
handler
the handler to invoke when the data view updates
service
the service to watch for changes
OPTIONAL PARAMETERS
-------------------
datacenter
can be provided to override the agent's default datacenter
state
if this watch is 'present' or 'absent'. Defaults to 'present'.
token
can be provided to override the agent's default ACL token
tag
filter by tag
BOOLEAN PARAMETERS
------------------
passingonly
specifies if only hosts passing all checks are displayed
EXAMPLES
--------
.. code-block:: sh
__consul_watch_service some-id \
--service consul \
--handler /usr/bin/my-handler.sh
__consul_watch_service some-id \
--service redis \
--tag production \
--handler /usr/bin/my-handler.sh
__consul_watch_service some-id \
--service redis \
--tag production \
--passingonly \
--handler /usr/bin/my-handler.sh
SEE ALSO
--------
:strong:`cdist-type__consul_agent`\ (7)
consul documentation at: <http://www.consul.io/docs/agent/watches.html>.
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2015 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

59
src/extra/manual/6.3.0/_sources/man7/cdist-type__consul_watch_services.rst.txt Normal file
View file

@ -0,0 +1,59 @@
cdist-type__consul_watch_services(7)
====================================
NAME
----
cdist-type__consul_watch_services - Manages consul services watches
DESCRIPTION
-----------
Generate and deploy watch definitions of type 'services' for a consul agent.
See http://www.consul.io/docs/agent/watches.html for parameter documentation.
REQUIRED PARAMETERS
-------------------
handler
the handler to invoke when the data view updates
OPTIONAL PARAMETERS
-------------------
datacenter
can be provided to override the agent's default datacenter
state
if this watch is 'present' or 'absent'. Defaults to 'present'.
token
can be provided to override the agent's default ACL token
EXAMPLES
--------
.. code-block:: sh
__consul_watch_services some-id \
--handler /usr/bin/my-key-handler.sh
SEE ALSO
--------
:strong:`cdist-type__consul_agent`\ (7)
consul documentation at: <http://www.consul.io/docs/agent/watches.html>.
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2015 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

84
src/extra/manual/6.3.0/_sources/man7/cdist-type__cron.rst.txt Normal file
View file

@ -0,0 +1,84 @@
cdist-type__cron(7)
===================
NAME
----
cdist-type__cron - Installs and manages cron jobs
DESCRIPTION
-----------
This cdist type allows you to manage entries in a users crontab.
REQUIRED PARAMETERS
-------------------
user
The user who's crontab is edited
command
The command to run.
OPTIONAL PARAMETERS
-------------------
state
Either present or absent. Defaults to present.
minute
See crontab(5). Defaults to *
hour
See crontab(5). Defaults to *
day_of_month
See crontab(5). Defaults to *
month
See crontab(5). Defaults to *
day_of_week
See crontab(5). Defaults to *
raw
Take whatever the user has given instead of time and date fields.
If given, all other time and date fields are ignored.
Can for example be used to specify cron EXTENSIONS like reboot, yearly etc.
See crontab(5) for the extensions if any that your cron implementation
implements.
raw_command
Take whatever the user has given in the command and ignore everything else.
If given, the command will be added to crontab.
Can for example be used to define variables like SHELL or MAILTO.
EXAMPLES
--------
.. code-block:: sh
# run Monday to Saturday at 23:15
__cron some-id --user root --command "/path/to/script" \
--hour 23 --minute 15 --day_of_week 1-6
# run on reboot
__cron some-id --user root --command "/path/to/script" \
--raw @reboot
# remove cronjob
__cron some-id --user root --command "/path/to/script" --state absent
# define default shell
__cron some-id --user root --raw_command --command "SHELL=/bin/bash" \
--state present
SEE ALSO
--------
:strong:`crontab`\ (5)
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2011-2013 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

54
src/extra/manual/6.3.0/_sources/man7/cdist-type__daemontools.rst.txt Normal file
View file

@ -0,0 +1,54 @@
cdist-type__daemontools(7)
==========================
NAME
----
cdist-type__daemontools - Install daemontools
DESCRIPTION
-----------
Install djb daemontools and (optionally) an init script.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
from-package
Package to install. Must be compatible with the original daemontools. Example: daemontools-encore. Default: daemontools.
servicedir
Directory to scan for services. Default: `/service`
BOOLEAN PARAMETERS
------------------
install-init-script
Add an init script and set it to start on boot.
EXAMPLES
--------
.. code-block:: sh
__daemontools --from-package daemontools-encore # if you prefer
SEE ALSO
--------
:strong:`cdist-type__daemontools_service`\ (7)
AUTHORS
-------
Kamila Součková <kamila--@--ksp.sk>
COPYING
-------
Copyright \(C) 2017 Kamila Součková. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

72
src/extra/manual/6.3.0/_sources/man7/cdist-type__daemontools_service.rst.txt Normal file
View file

@ -0,0 +1,72 @@
cdist-type__daemontools_service(7)
==================================
NAME
----
cdist-type__daemontools_service - Create a daemontools-compatible service dir.
DESCRIPTION
-----------
Create a directory structure compatible with daemontools-like service management.
Note that svc must be present on the target system.
The object ID will be used as the service name.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
run
Command to run. exec-ing and stderr redirection will be added. One of run, run-file must be specified.
Example: `my-program`
run-file
File to save as <servicedir>/run. One of run, run-file must be specified.
Example:
.. code-block:: sh
#!/bin/sh
exec 2>&1
exec my_program
log-run
Command to run for log consumption. Default: `multilog t ./main`
servicedir
Directory to install into. Default: `/service`
BOOLEAN PARAMETERS
------------------
None.
EXAMPLES
--------
.. code-block:: sh
require="__daemontools" __daemontools_service prometheus --run "setuidgid prometheus $GOBIN/prometheus $FLAGS"
SEE ALSO
--------
:strong:`cdist-type__daemontools`\ (7)
AUTHORS
-------
Kamila Součková <kamila--@--ksp.sk>
COPYING
-------
Copyright \(C) 2017 Kamila Součková. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

53
src/extra/manual/6.3.0/_sources/man7/cdist-type__debconf_set_selections.rst.txt Normal file
View file

@ -0,0 +1,53 @@
cdist-type__debconf_set_selections(7)
=====================================
NAME
----
cdist-type__debconf_set_selections - Setup debconf selections
DESCRIPTION
-----------
On Debian and alike systems debconf-set-selections(1) can be used
to setup configuration parameters.
REQUIRED PARAMETERS
-------------------
file
Use the given filename as input for debconf-set-selections(1)
If filename is "-", read from stdin.
EXAMPLES
--------
.. code-block:: sh
# Setup configuration for nslcd
__debconf_set_selections nslcd --file /path/to/file
# Setup configuration for nslcd from another type
__debconf_set_selections nslcd --file "$__type/files/preseed/nslcd"
__debconf_set_selections nslcd --file - << eof
gitolite gitolite/gituser string git
eof
SEE ALSO
--------
:strong:`debconf-set-selections`\ (1), :strong:`cdist-type__update_alternatives`\ (7)
AUTHORS
-------
Nico Schottelius <nico-cdist--@--schottelius.org>
COPYING
-------
Copyright \(C) 2011-2014 Nico Schottelius. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

101
src/extra/manual/6.3.0/_sources/man7/cdist-type__directory.rst.txt Normal file
View file

@ -0,0 +1,101 @@
cdist-type__directory(7)
========================
NAME
----
cdist-type__directory - Manage a directory
DESCRIPTION
-----------
This cdist type allows you to create or remove directories on the target.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
state
'present' or 'absent', defaults to 'present'
group
Group to chgrp to.
mode
Unix permissions, suitable for chmod.
owner
User to chown to.
BOOLEAN PARAMETERS
------------------
parents
Whether to create parents as well (mkdir -p behaviour).
Warning: all intermediate directory permissions default
to whatever mkdir -p does.
Usually this means root:root, 0700.
recursive
If supplied the chgrp and chown call will run recursively.
This does *not* influence the behaviour of chmod.
MESSAGES
--------
chgrp <group>
Changed group membership
chown <owner>
Changed owner
chmod <mode>
Changed mode
create
Empty directory was created
remove
Directory exists, but state is absent, directory will be removed by generated code.
remove non directory
Something other than a directory with the same name exists and was removed prior to create.
EXAMPLES
--------
.. code-block:: sh
# A silly example
__directory /tmp/foobar
# Remove a directory
__directory /tmp/foobar --state absent
# Ensure /etc exists correctly
__directory /etc --owner root --group root --mode 0755
# Create nfs service directory, including parents
__directory /home/services/nfs --parents
# Change permissions recursively
__directory /home/services --recursive --owner root --group root
# Setup a temp directory
__directory /local --mode 1777
# Take it all
__directory /home/services/kvm --recursive --parents \
--owner root --group root --mode 0755 --state present
AUTHORS
-------
Nico Schottelius <nico-cdist--@--schottelius.org>
COPYING
-------
Copyright \(C) 2011 Nico Schottelius. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

55
src/extra/manual/6.3.0/_sources/man7/cdist-type__docker.rst.txt Normal file
View file

@ -0,0 +1,55 @@
cdist-type__docker(7)
=====================
NAME
----
cdist-type__docker - install Docker CE
DESCRIPTION
-----------
Installs latest Docker Community Edition package.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
state
'present' or 'absent', defaults to 'present'
version
The specific version to install. Defaults to the special value 'latest',
meaning the version the package manager will install by default.
BOOLEAN PARAMETERS
------------------
None.
EXAMPLES
--------
.. code-block:: sh
# Install docker
__docker
# Remove docker
__docker --state absent
# Install specific version
__docker --state present --version 18.03.0.ce
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2016 Steven Armstrong. Free use of this software is
granted under the terms of the GNU General Public License version 3 (GPLv3).

58
src/extra/manual/6.3.0/_sources/man7/cdist-type__docker_compose.rst.txt Normal file
View file

@ -0,0 +1,58 @@
cdist-type__docker_compose(7)
=============================
NAME
----
cdist-type__docker_compose - install docker-compose
DESCRIPTION
-----------
Installs docker-compose package.
State 'absent' will not remove docker binary itself,
only docker-compose binary will be removed
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
version
Define docker_compose version, defaults to "1.9.0"
state
'present' or 'absent', defaults to 'present'
BOOLEAN PARAMETERS
------------------
None.
EXAMPLES
--------
.. code-block:: sh
# Install docker-compose
__docker_compose
# Install version 1.9.0-rc4
__docker_compose --version 1.9.0-rc4
# Remove docker-compose
__docker_compose --state absent
AUTHORS
-------
Dominique Roux <dominique.roux--@--ungleich.ch>
COPYING
-------
Copyright \(C) 2016 Dominique Roux. Free use of this software is
granted under the terms of the GNU General Public License version 3 or later (GPLv3+).

55
src/extra/manual/6.3.0/_sources/man7/cdist-type__docker_config.rst.txt Normal file
View file

@ -0,0 +1,55 @@
cdist-type__docker_config(7)
============================
NAME
----
cdist-type__docker_config - Manage Docker configs
DESCRIPTION
-----------
This type manages Docker configs.
OPTIONAL PARAMETERS
-------------------
source
Path to the source file. If it is '-' (dash), read standard input.
state
'present' or 'absent', defaults to 'present' where:
present
if the config does not exist, it is created
absent
the config is removed
CAVEATS
-------
Since Docker configs cannot be updated once created, this type tries removing
and recreating the config if it changes. If the config is used by a service at
the time of removing, then this type will fail.
EXAMPLES
--------
.. code-block:: sh
# Creates "foo" config from "bar" source file
__docker_config foo --source bar
AUTHORS
-------
Ľubomír Kučera <lubomir.kucera.jr at gmail.com>
COPYING
-------
Copyright \(C) 2018 Ľubomír Kučera. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

54
src/extra/manual/6.3.0/_sources/man7/cdist-type__docker_secret.rst.txt Normal file
View file

@ -0,0 +1,54 @@
cdist-type__docker_secret(7)
============================
NAME
----
cdist-type__docker_secret - Manage Docker secrets
DESCRIPTION
-----------
This type manages Docker secrets.
OPTIONAL PARAMETERS
-------------------
source
Path to the source file. If it is '-' (dash), read standard input.
state
'present' or 'absent', defaults to 'present' where:
present
if the secret does not exist, it is created
absent
the secret is removed
CAVEATS
-------
Since Docker secrets cannot be updated once created, this type takes no action
if the specified secret already exists.
EXAMPLES
--------
.. code-block:: sh
# Creates "foo" secret from "bar" source file
__docker_secret foo --source bar
AUTHORS
-------
Ľubomír Kučera <lubomir.kucera.jr at gmail.com>
COPYING
-------
Copyright \(C) 2018 Ľubomír Kučera. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

54
src/extra/manual/6.3.0/_sources/man7/cdist-type__docker_stack.rst.txt Normal file
View file

@ -0,0 +1,54 @@
cdist-type__docker_stack(7)
===========================
NAME
----
cdist-type__docker_stack - Manage Docker stacks
DESCRIPTION
-----------
This type manages service stacks.
.. note::
Since there is no easy way to tell whether a stack needs to be updated,
`docker stack deploy` is being run every time this type is invoked.
However, it does not mean this type is not idempotent. If Docker does not
detect changes, the existing stack will not be updated.
OPTIONAL PARAMETERS
-------------------
compose-file
Path to the compose file. If it is '-' (dash), read standard input.
state
'present' or 'absent', defaults to 'present' where:
present
the stack is deployed
absent
the stack is removed
EXAMPLES
--------
.. code-block:: sh
# Deploys 'foo' stack defined in 'docker-compose.yml' compose file
__docker_stack foo --compose-file docker-compose.yml
AUTHORS
-------
Ľubomír Kučera <lubomir.kucera.jr at gmail.com>
COPYING
-------
Copyright \(C) 2018 Ľubomír Kučera. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

49
src/extra/manual/6.3.0/_sources/man7/cdist-type__docker_swarm.rst.txt Normal file
View file

@ -0,0 +1,49 @@
cdist-type__docker_swarm(7)
===========================
NAME
----
cdist-type__docker_swarm - Manage Swarm
DESCRIPTION
-----------
This type can initialize Docker swarm mode. For more information about swarm
mode, see `Swarm mode overview <https://docs.docker.com/engine/swarm/>`_.
OPTIONAL PARAMETERS
-------------------
state
'present' or 'absent', defaults to 'present' where:
present
Swarm is initialized
absent
Swarm is left
EXAMPLES
--------
.. code-block:: sh
# Initializes a swarm
__docker_swarm
# Leaves a swarm
__docker_swarm --state absent
AUTHORS
-------
Ľubomír Kučera <lubomir.kucera.jr at gmail.com>
COPYING
-------
Copyright \(C) 2018 Ľubomír Kučera. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

59
src/extra/manual/6.3.0/_sources/man7/cdist-type__dog_vdi.rst.txt Normal file
View file

@ -0,0 +1,59 @@
cdist-type__dog_vdi(7)
======================
NAME
----
cdist-type__dog_vdi - Manage Sheepdog VM images
DESCRIPTION
-----------
The dog program is used to create images for sheepdog
to be used in qemu.
OPTIONAL PARAMETERS
-------------------
state
Either "present" or "absent", defaults to "present"
size
Size of the image in "dog vdi" compatible units.
Required if state is "present".
EXAMPLES
--------
.. code-block:: sh
# Create a 50G size image
__dog_vdi nico-privat.sky.ungleich.ch --size 50G
# Create a 50G size image (more explicit)
__dog_vdi nico-privat.sky.ungleich.ch --size 50G --state present
# Remove image
__dog_vdi nico-privat.sky.ungleich.ch --state absent
# Remove image - keeping --size is ok
__dog_vdi nico-privat.sky.ungleich.ch --size 50G --state absent
SEE ALSO
--------
:strong:`qemu`\ (1), :strong:`dog`\ (8)
AUTHORS
-------
Nico Schottelius <nico-cdist--@--schottelius.org>
COPYING
-------
Copyright \(C) 2014 Nico Schottelius. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

71
src/extra/manual/6.3.0/_sources/man7/cdist-type__dot_file.rst.txt Normal file
View file

@ -0,0 +1,71 @@
cdist-type__dot_file(7)
========================
NAME
----
cdist-type__dot_file - install file under user's home directory
DESCRIPTION
-----------
This type installs a file (=\ *__object_id*) under user's home directory,
providing a way to install per-user configuration files. File owner
and group is deduced from user, for who file is installed.
Unlike regular __file type, you do not need make any assumptions,
where user's home directory is.
REQUIRED PARAMETERS
-------------------
user
User, for who file is installed
OPTIONAL PARAMETERS
-------------------
mode
forwarded to :strong:`__file` type
state
forwarded to :strong:`__file` type
source
forwarded to :strong:`__file` type
MESSAGES
--------
This type inherits all messages from :strong:`file` type, and do not add
any new.
EXAMPLES
--------
.. code-block:: sh
# Install .forward file for user 'alice'. Since state is 'present',
# user is not meant to edit this file, all changes will be overridden.
# It is good idea to put warning about it in file itself.
__dot_file .forward --user alice --source "$__files/forward"
# Install .muttrc for user 'bob', if not already present. User can safely
# edit it, his changes will not be overwritten.
__dot_file .muttrc --user bob --source "$__files/recommended_mutt_config" --state exists
# Install default xmonad config for user 'eve'. Parent directory is created automatically.
__dot_file .xmonad/xmonad.hs --user eve --state exists --source "$__files/xmonad.hs"
SEE ALSO
--------
**cdist-type__file**\ (7)
COPYING
-------
Copyright (C) 2015 Dmitry Bogatov. Free use of this software is granted
under the terms of the GNU General Public License version 3 or later
(GPLv3+).

124
src/extra/manual/6.3.0/_sources/man7/cdist-type__file.rst.txt Normal file
View file

@ -0,0 +1,124 @@
cdist-type__file(7)
===================
NAME
----
cdist-type__file - Manage files.
DESCRIPTION
-----------
This cdist type allows you to create files, remove files and set file
attributes on the target.
If the file already exists on the target, then if it is a:
regular file, and state is:
present
replace it with the source file if they are not equal
exists
do nothing
symlink
replace it with the source file
directory
replace it with the source file
One exception is that when state is pre-exists, an error is raised if
the file would have been created otherwise (e.g. it is not present or
not a regular file).
In any case, make sure that the file attributes are as specified.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
state
'present', 'absent', 'exists' or 'pre-exists', defaults to 'present' where:
present
the file is exactly the one from source
absent
the file does not exist
exists
the file from source but only if it doesn't already exist
pre-exists
check that the file exists and is a regular file, but do not
create or modify it
group
Group to chgrp to.
mode
Unix permissions, suitable for chmod.
owner
User to chown to.
source
If supplied, copy this file from the host running cdist to the target.
If not supplied, an empty file or directory will be created.
If source is '-' (dash), take what was written to stdin as the file content.
onchange
The code to run if file is modified.
MESSAGES
--------
chgrp <group>
Changed group membership
chown <owner>
Changed owner
chmod <mode>
Changed mode
create
Empty file was created (no --source specified)
remove
File exists, but state is absent, file will be removed by generated code.
upload
File was uploaded
EXAMPLES
--------
.. code-block:: sh
# Create /etc/cdist-configured as an empty file
__file /etc/cdist-configured
# The same thing
__file /etc/cdist-configured --state present
# Use __file from another type
__file /etc/issue --source "$__type/files/archlinux" --state present
# Delete existing file
__file /etc/cdist-configured --state absent
# Supply some more settings
__file /etc/shadow --source "$__type/files/shadow" \
--owner root --group shadow --mode 0640 \
--state present
# Provide a default file, but let the user change it
__file /home/frodo/.bashrc --source "/etc/skel/.bashrc" \
--state exists \
--owner frodo --mode 0600
# Check that the file is present, show an error when it is not
__file /etc/somefile --state pre-exists
# Take file content from stdin
__file /tmp/whatever --owner root --group root --mode 644 --source - << DONE
Here goes the content for /tmp/whatever
DONE
AUTHORS
-------
Nico Schottelius <nico-cdist--@--schottelius.org>
COPYING
-------
Copyright \(C) 2011-2013 Nico Schottelius. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

81
src/extra/manual/6.3.0/_sources/man7/cdist-type__filesystem.rst.txt Normal file
View file

@ -0,0 +1,81 @@
cdist-type__filesystem(7)
=========================
NAME
----
cdist-type__filesystem - Create Filesystems.
DESCRIPTION
-----------
This cdist type allows you to create filesystems on devices.
If the device is mounted on target, it refuses to do anything.
If the device has a filesystem other then the specified and/or
the label is not correct, it only makes a new filesystem
if you have specified --force option.
REQUIRED PARAMETERS
-------------------
fstype
Filesystem type, for example 'ext3', 'btrfs' or 'xfs'.
OPTIONAL PARAMETERS
-------------------
device
Blockdevice for filesystem, Defaults to object_id.
On linux, it can be any lsblk accepted device notation.
|
| For example:
| /dev/sdx
| or /dev/disk/by-xxxx/xxx
| or /dev/mapper/xxxx
label
Label which should be applied on the filesystem.
mkfsoptions
Additional options which are inserted to the mkfs.xxx call.
BOOLEAN PARAMETERS
------------------
force
Normally, this type does nothing if a filesystem is found
on the target device. If you specify force, it's formatted
if the filesystem type or label differs from parameters.
Warning: This option can easily lead into data loss!
MESSAGES
--------
filesystem <fstype> on <device> \: <discoverd device> created
Filesystem was created on <discoverd device>
EXAMPLES
--------
.. code-block:: sh
# Ensures that device /dev/sdb is formatted with xfs
__filesystem /dev/sdb --fstype xfs --label Testdisk1
# The same thing with btrfs and disk spezified by pci path to disk 1:0 on vmware
__filesystem dev_sdb --fstype btrfs --device /dev/disk/by-path/pci-0000:0b:00.0-scsi-0:0:0:0 --label Testdisk2
# Make sure that a multipath san device has a filesystem ...
__filesystem dev_sdb --fstype xfs --device /dev/mapper/360060e80432f560050202f22000023ff --label Testdisk3
AUTHORS
-------
Daniel Heule <hda--@--sfs.biz>
COPYING
-------
Copyright \(C) 2016 Daniel Heule. Free use of this software is
granted under the terms of the GNU General Public License version 3 or any later version (GPLv3+).

81
src/extra/manual/6.3.0/_sources/man7/cdist-type__firewalld_rule.rst.txt Normal file
View file

@ -0,0 +1,81 @@
cdist-type__firewalld_rule(7)
=============================
NAME
----
cdist-type__firewalld_rule - Configure firewalld rules
DESCRIPTION
-----------
This cdist type allows you to manage rules in firewalld
using the *direct* way (i.e. no zone support).
REQUIRED PARAMETERS
-------------------
rule
The rule to apply. Essentially an firewalld command
line without firewalld in front of it.
protocol
Either ipv4, ipv4 or eb. See firewall-cmd(1)
table
The table to use (like filter or nat). See firewall-cmd(1).
chain
The chain to use (like INPUT_direct or FORWARD_direct). See firewall-cmd(1).
priority
The priority to use (0 is topmost). See firewall-cmd(1).
OPTIONAL PARAMETERS
-------------------
state
'present' or 'absent', defaults to 'present'
EXAMPLES
--------
.. code-block:: sh
# Allow access from entrance.place4.ungleich.ch
__firewalld_rule entrance \
--protocol ipv4 \
--table filter \
--chain INPUT_direct \
--priority 0 \
--rule '-s entrance.place4.ungleich.ch -j ACCEPT'
# Allow forwarding of traffic from br0
__firewalld_rule vm-forward --protocol ipv4 \
--table filter \
--chain FORWARD_direct \
--priority 0 \
--rule '-i br0 -j ACCEPT'
# Ensure old rule is absent - warning, the rule part must stay the same!
__firewalld_rule vm-forward
--protocol ipv4 \
--table filter \
--chain FORWARD_direct \
--priority 0 \
--rule '-i br0 -j ACCEPT' \
--state absent
SEE ALSO
--------
:strong:`cdist-type__iptables_rule`\ (7), :strong:`firewalld`\ (8)
AUTHORS
-------
Nico Schottelius <nico-cdist--@--schottelius.org>
COPYING
-------
Copyright \(C) 2015 Nico Schottelius. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

53
src/extra/manual/6.3.0/_sources/man7/cdist-type__firewalld_start.rst.txt Normal file
View file

@ -0,0 +1,53 @@
cdist-type__firewalld_start(7)
==============================
NAME
----
cdist-type__firewalld_start - start and enable firewalld
DESCRIPTION
-----------
This cdist type allows you to start and enable firewalld.
REQUIRED PARAMETERS
-------------------
None
OPTIONAL PARAMETERS
-------------------
startstate
'present' or 'absent', start/stop firewalld. Default is 'present'.
bootstate
'present' or 'absent', enable/disable firewalld on boot. Default is 'present'.
EXAMPLES
--------
.. code-block:: sh
# start and enable firewalld
__firewalld_start
# only enable firewalld to start on boot
__firewalld_start --startstate present --bootstate absent
SEE ALSO
--------
:strong:`firewalld`\ (8)
AUTHORS
-------
Darko Poljak <darko.poljak--@--ungleich.ch>
COPYING
-------
Copyright \(C) 2016 Darko Poljak. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

66
src/extra/manual/6.3.0/_sources/man7/cdist-type__git.rst.txt Normal file
View file

@ -0,0 +1,66 @@
cdist-type__git(7)
==================
NAME
----
cdist-type__git - Get and or keep git repositories up-to-date
DESCRIPTION
-----------
This cdist type allows you to clone git repositories
REQUIRED PARAMETERS
-------------------
source
Specifies the git remote to clone from
OPTIONAL PARAMETERS
-------------------
state
Either "present" or "absent", defaults to "present"
branch
Create this branch by checking out the remote branch of this name
Default branch is "master"
group
Group to chgrp to.
mode
Unix permissions, suitable for chmod.
owner
User to chown to.
recursive
Passes the --recurse-submodules flag to git when cloning the repository.
shallow
Sets --depth=1 and --shallow-submodules for cloning repositories with big history.
EXAMPLES
--------
.. code-block:: sh
__git /home/services/dokuwiki --source git://github.com/splitbrain/dokuwiki.git
# Checkout cdist, stay on branch 2.1
__git /home/nico/cdist --source git@code.ungleich.ch:ungleich-public/cdist.git --branch 2.1
AUTHORS
-------
Nico Schottelius <nico-cdist--@--schottelius.org>
COPYING
-------
Copyright \(C) 2012 Nico Schottelius. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

48
src/extra/manual/6.3.0/_sources/man7/cdist-type__go_get.rst.txt Normal file
View file

@ -0,0 +1,48 @@
cdist-type__go_get(7)
=====================
NAME
----
cdist-type__go_get - Install go packages with go get
DESCRIPTION
-----------
This cdist type allows you to install golang packages with go get.
A sufficiently recent version of go must be present on the system.
The object ID is the go package to be installed.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
None.
EXAMPLES
--------
.. code-block:: sh
__go_get github.com/prometheus/prometheus/cmd/...
# usually you'd need to require golang from somewhere:
require="__golang_from_vendor" __go_get github.com/prometheus/prometheus/cmd/...
AUTHORS
-------
Kamila Součková <kamila@ksp.sk>
COPYING
-------
Copyright \(C) 2017 Kamila Součková. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

48
src/extra/manual/6.3.0/_sources/man7/cdist-type__golang_from_vendor.rst.txt Normal file
View file

@ -0,0 +1,48 @@
cdist-type__golang_from_vendor(7)
=================================
NAME
----
cdist-type__golang_from_vendor - Install any version of golang from golang.org
DESCRIPTION
-----------
This cdist type allows you to install golang from archives provided by https://golang.org/dl/.
See https://golang.org/dl/ for the list of supported versions, operating systems and architectures.
This is a singleton type.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
version
The golang version to install, defaults to 1.8.1
EXAMPLES
--------
.. code-block:: sh
__golang_from_vendor --version 1.8.1
AUTHORS
-------
Kamila Součková <kamila@ksp.sk>
COPYING
-------
Copyright \(C) 2017 Kamila Součková. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

43
src/extra/manual/6.3.0/_sources/man7/cdist-type__grafana_dashboard.rst.txt Normal file
View file

@ -0,0 +1,43 @@
cdist-type__grafana_dashboard(7)
================================
NAME
----
cdist-type__grafana_dashboard - Install Grafana (https://grafana.com)
DESCRIPTION
-----------
This cdist type adds the Grafana repository, installs the grafana package, and sets the server to start on boot.
This is a singleton type.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
None.
EXAMPLES
--------
.. code-block:: sh
__grafana_dashboard
AUTHORS
-------
Kamila Součková <kamila@ksp.sk>
COPYING
-------
Copyright \(C) 2017 Kamila Součková. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

80
src/extra/manual/6.3.0/_sources/man7/cdist-type__group.rst.txt Normal file
View file

@ -0,0 +1,80 @@
cdist-type__group(7)
====================
NAME
----
cdist-type__group - Manage groups
DESCRIPTION
-----------
This cdist type allows you to create or modify groups on the target.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
state
absent or present, defaults to present
gid
see groupmod(8)
password
see above
BOOLEAN PARAMETERS
------------------
system
see groupadd(8), apply only on group creation
MESSAGES
--------
mod
group is modified
add
New group added
remove
group is removed
change <property> <new_value> <current_value>
Changed group property from current_value to new_value
set <property> <new_value>
set property to new value, property was not set before
EXAMPLES
--------
.. code-block:: sh
# Create a group 'foobar' with operating system default settings
__group foobar
# Remove the 'foobar' group
__group foobar --state absent
# Create a system group 'myservice' with operating system default settings
__group myservice --system
# Same but with a specific gid
__group foobar --gid 1234
# Same but with a gid and password
__group foobar --gid 1234 --password 'crypted-password-string'
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2011-2015 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

55
src/extra/manual/6.3.0/_sources/man7/cdist-type__hostname.rst.txt Normal file
View file

@ -0,0 +1,55 @@
cdist-type__hostname(7)
=======================
NAME
----
cdist-type__hostname - Set the hostname
DESCRIPTION
-----------
Sets the hostname on various operating systems.
**Tip:** For advice on choosing a hostname, see
`RFC 1178 <https://tools.ietf.org/html/rfc1178>`_.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
name
The hostname to set. Defaults to the first segment of __target_host
(${__target_host%%.*})
MESSAGES
--------
changed
Changed the hostname
EXAMPLES
--------
.. code-block:: sh
# take hostname from __target_host
__hostname
# set hostname explicitly
__hostname --name some-static-hostname
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2012 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

55
src/extra/manual/6.3.0/_sources/man7/cdist-type__hosts.rst.txt Normal file
View file

@ -0,0 +1,55 @@
cdist-type__hosts(7)
====================
NAME
----
cdist-type__hosts - manage entries in /etc/hosts
DESCRIPTION
-----------
Add or remove entries from */etc/hosts* file.
OPTIONAL PARAMETERS
-------------------
state
If state is ``present``, make *object_id* resolve to *ip*. If
state is ``absent``, *object_id* will no longer resolve via
*/etc/hosts*, if it was previously configured with this type.
Manually inserted entries are unaffected.
ip
IP address, to which hostname (=\ *object_id*) must resolve. If
state is ``present``, this parameter is mandatory, if state is
``absent``, this parameter is silently ignored.
EXAMPLES
--------
.. code-block:: sh
# Now `funny' resolves to 192.168.1.76,
__hosts funny --ip 192.168.1.76
# and `happy' no longer resolve via /etc/hosts if it was
# previously configured via __hosts.
__hosts happy --state absent
SEE ALSO
--------
:strong:`hosts`\ (5)
AUTHORS
-------
Dmitry Bogatov <KAction@gnu.org>
COPYING
-------
Copyright (C) 2015,2016 Dmitry Bogatov. Free use of this software is granted
under the terms of the GNU General Public License version 3 or later
(GPLv3+).

48
src/extra/manual/6.3.0/_sources/man7/cdist-type__install_bootloader_grub.rst.txt Normal file
View file

@ -0,0 +1,48 @@
cdist-type__install_bootloader_grub(7)
======================================
NAME
----
cdist-type__install_bootloader_grub - install grub2 bootloader on given disk
DESCRIPTION
-----------
This cdist type allows you to install grub2 bootloader on given disk.
REQUIRED PARAMETERS
-------------------
None
OPTIONAL PARAMETERS
-------------------
device
The device to install grub to. Defaults to object_id
chroot
where to chroot before running grub-install. Defaults to /target.
EXAMPLES
--------
.. code-block:: sh
__install_bootloader_grub /dev/sda
__install_bootloader_grub /dev/sda --chroot /mnt/foobar
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2011 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

42
src/extra/manual/6.3.0/_sources/man7/cdist-type__install_chroot_mount.rst.txt Normal file
View file

@ -0,0 +1,42 @@
cdist-type__install_chroot_mount(7)
===================================
NAME
----
cdist-type__install_chroot_mount - mount a chroot with install command
DESCRIPTION
-----------
Mount and prepare a chroot for running commands within it.
REQUIRED PARAMETERS
-------------------
None
OPTIONAL PARAMETERS
-------------------
None
EXAMPLES
--------
.. code-block:: sh
__install_chroot_mount /path/to/chroot
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2012 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

47
src/extra/manual/6.3.0/_sources/man7/cdist-type__install_chroot_umount.rst.txt Normal file
View file

@ -0,0 +1,47 @@
cdist-type__install_chroot_umount(7)
====================================
NAME
----
cdist-type__install_chroot_umount - unmount a chroot mounted by __install_chroot_mount
DESCRIPTION
-----------
Undo what __install_chroot_mount did.
REQUIRED PARAMETERS
-------------------
None
OPTIONAL PARAMETERS
-------------------
None
EXAMPLES
--------
.. code-block:: sh
__install_chroot_umount /path/to/chroot
SEE ALSO
--------
:strong:`cdist-type__install_chroot_mount`\ (7)
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2012 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

47
src/extra/manual/6.3.0/_sources/man7/cdist-type__install_config.rst.txt Normal file
View file

@ -0,0 +1,47 @@
cdist-type__install_config(7)
=============================
NAME
----
cdist-type__install_config - run cdist config as part of the installation
DESCRIPTION
-----------
This cdist type allows you to run cdist config as part of the installation.
It does this by using a custom __remote_{copy,exec} prefix which runs
cdist config against the /target chroot on the remote host.
REQUIRED PARAMETERS
-------------------
None
OPTIONAL PARAMETERS
-------------------
chroot
where to chroot before running grub-install. Defaults to /target.
EXAMPLES
--------
.. code-block:: sh
__install_config
__install_config --chroot /mnt/somewhere
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2011 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

50
src/extra/manual/6.3.0/_sources/man7/cdist-type__install_coreos.rst.txt Normal file
View file

@ -0,0 +1,50 @@
cdist-type__install_coreos(7)
=============================
NAME
----
cdist-type__install_coreos - Install CoreOS
DESCRIPTION
-----------
This type installs CoreOS to a given device using coreos-install_, which is
present in CoreOS ISO by default.
.. _coreos-install: https://raw.githubusercontent.com/coreos/init/master/bin/coreos-install
REQUIRED PARAMETERS
-------------------
device
A device CoreOS will be installed to.
OPTIONAL PARAMETERS
-------------------
ignition
Path to ignition config.
EXAMPLES
--------
.. code-block:: sh
__install_coreos \
--device /dev/sda \
--ignition ignition.json
AUTHORS
-------
Ľubomír Kučera <lubomir.kucera.jr at gmail.com>
COPYING
-------
Copyright \(C) 2018 Ľubomír Kučera. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

101
src/extra/manual/6.3.0/_sources/man7/cdist-type__install_directory.rst.txt Normal file
View file

@ -0,0 +1,101 @@
cdist-type__install_directory(7)
================================
NAME
----
cdist-type__install_directory - Manage a directory with install command
DESCRIPTION
-----------
This cdist type allows you to create or remove directories on the target.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
state
'present' or 'absent', defaults to 'present'
group
Group to chgrp to.
mode
Unix permissions, suitable for chmod.
owner
User to chown to.
BOOLEAN PARAMETERS
------------------
parents
Whether to create parents as well (mkdir -p behaviour).
Warning: all intermediate directory permissions default
to whatever mkdir -p does.
Usually this means root:root, 0700.
recursive
If supplied the chgrp and chown call will run recursively.
This does *not* influence the behaviour of chmod.
MESSAGES
--------
chgrp <group>
Changed group membership
chown <owner>
Changed owner
chmod <mode>
Changed mode
create
Empty directory was created
remove
Directory exists, but state is absent, directory will be removed by generated code.
remove non directory
Something other than a directory with the same name exists and was removed prior to create.
EXAMPLES
--------
.. code-block:: sh
# A silly example
__install_directory /tmp/foobar
# Remove a directory
__install_directory /tmp/foobar --state absent
# Ensure /etc exists correctly
__install_directory /etc --owner root --group root --mode 0755
# Create nfs service directory, including parents
__install_directory /home/services/nfs --parents
# Change permissions recursively
__install_directory /home/services --recursive --owner root --group root
# Setup a temp directory
__install_directory /local --mode 1777
# Take it all
__install_directory /home/services/kvm --recursive --parents \
--owner root --group root --mode 0755 --state present
AUTHORS
-------
Nico Schottelius <nico-cdist--@--schottelius.org>
COPYING
-------
Copyright \(C) 2011 Nico Schottelius. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

124
src/extra/manual/6.3.0/_sources/man7/cdist-type__install_file.rst.txt Normal file
View file

@ -0,0 +1,124 @@
cdist-type__install_file(7)
===========================
NAME
----
cdist-type__install_file - Manage files with install command.
DESCRIPTION
-----------
This cdist type allows you to create files, remove files and set file
attributes on the target.
If the file already exists on the target, then if it is a:
regular file, and state is:
present
replace it with the source file if they are not equal
exists
do nothing
symlink
replace it with the source file
directory
replace it with the source file
One exception is that when state is pre-exists, an error is raised if
the file would have been created otherwise (e.g. it is not present or
not a regular file).
In any case, make sure that the file attributes are as specified.
REQUIRED PARAMETERS
-------------------
None.
OPTIONAL PARAMETERS
-------------------
state
'present', 'absent', 'exists' or 'pre-exists', defaults to 'present' where:
present
the file is exactly the one from source
absent
the file does not exist
exists
the file from source but only if it doesn't already exist
pre-exists
check that the file exists and is a regular file, but do not
create or modify it
group
Group to chgrp to.
mode
Unix permissions, suitable for chmod.
owner
User to chown to.
source
If supplied, copy this file from the host running cdist to the target.
If not supplied, an empty file or directory will be created.
If source is '-' (dash), take what was written to stdin as the file content.
onchange
The code to run if file is modified.
MESSAGES
--------
chgrp <group>
Changed group membership
chown <owner>
Changed owner
chmod <mode>
Changed mode
create
Empty file was created (no --source specified)
remove
File exists, but state is absent, file will be removed by generated code.
upload
File was uploaded
EXAMPLES
--------
.. code-block:: sh
# Create /etc/cdist-configured as an empty file
__install_file /etc/cdist-configured
# The same thing
__install_file /etc/cdist-configured --state present
# Use __file from another type
__install_file /etc/issue --source "$__type/files/archlinux" --state present
# Delete existing file
__install_file /etc/cdist-configured --state absent
# Supply some more settings
__install_file /etc/shadow --source "$__type/files/shadow" \
--owner root --group shadow --mode 0640 \
--state present
# Provide a default file, but let the user change it
__install_file /home/frodo/.bashrc --source "/etc/skel/.bashrc" \
--state exists \
--owner frodo --mode 0600
# Check that the file is present, show an error when it is not
__install_file /etc/somefile --state pre-exists
# Take file content from stdin
__install_file /tmp/whatever --owner root --group root --mode 644 --source - << DONE
Here goes the content for /tmp/whatever
DONE
AUTHORS
-------
Nico Schottelius <nico-cdist--@--schottelius.org>
COPYING
-------
Copyright \(C) 2011-2013 Nico Schottelius. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

53
src/extra/manual/6.3.0/_sources/man7/cdist-type__install_fstab.rst.txt Normal file
View file

@ -0,0 +1,53 @@
cdist-type__install_fstab(7)
============================
NAME
----
cdist-type__install_fstab - generate /etc/fstab during installation
DESCRIPTION
-----------
Uses __install_generate_fstab to generate a /etc/fstab file and uploads it
to the target machine at ${prefix}/etc/fstab.
REQUIRED PARAMETERS
-------------------
None
OPTIONAL PARAMETERS
-------------------
prefix
The prefix under which to generate the /etc/fstab file.
Defaults to /target.
EXAMPLES
--------
.. code-block:: sh
__install_fstab
__install_fstab --prefix /mnt/target
SEE ALSO
--------
:strong:`cdist-type__install_generate_fstab`\ (7),
:strong:`cdist-type__install_mount`\ (7)
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2011 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

53
src/extra/manual/6.3.0/_sources/man7/cdist-type__install_generate_fstab.rst.txt Normal file
View file

@ -0,0 +1,53 @@
cdist-type__install_generate_fstab(7)
=====================================
NAME
----
cdist-type__install_generate_fstab - generate /etc/fstab during installation
DESCRIPTION
-----------
Generates a /etc/fstab file from information retrieved from
__install_mount definitions.
REQUIRED PARAMETERS
-------------------
destination
The path where to store the generated fstab file.
Note that this is a path on the server, where cdist is running, not the target host.
OPTIONAL PARAMETERS
-------------------
None
BOOLEAN PARAMETERS
-------------------
uuid
use UUID instead of device in fstab
EXAMPLES
--------
.. code-block:: sh
__install_generate_fstab --destination /path/where/you/want/fstab
__install_generate_fstab --uuid --destination /path/where/you/want/fstab
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2012 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

62
src/extra/manual/6.3.0/_sources/man7/cdist-type__install_mkfs.rst.txt Normal file
View file

@ -0,0 +1,62 @@
cdist-type__install_mkfs(7)
===========================
NAME
----
cdist-type__install_mkfs - build a linux file system
DESCRIPTION
-----------
This cdist type is a wrapper for the mkfs command.
REQUIRED PARAMETERS
-------------------
type
The filesystem type to use. Same as used with mkfs -t.
OPTIONAL PARAMETERS
-------------------
device
defaults to object_id
options
file system-specific options to be passed to the mkfs command
blocks
the number of blocks to be used for the file system
EXAMPLES
--------
.. code-block:: sh
# reiserfs /dev/sda5
__install_mkfs /dev/sda5 --type reiserfs
# same thing with explicit device
__install_mkfs whatever --device /dev/sda5 --type reiserfs
# jfs with journal on /dev/sda2
__install_mkfs /dev/sda1 --type jfs --options "-j /dev/sda2"
SEE ALSO
--------
:strong:`mkfs`\ (8)
AUTHORS
-------
Steven Armstrong <steven-cdist--@--armstrong.cc>
COPYING
-------
Copyright \(C) 2011 Steven Armstrong. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

Some files were not shown because too many files have changed in this diff Show more