4. How to install cdist

4.1. Requirements

4.1.1. 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)

4.1.2. Target Hosts

  • /bin/sh: A posix like shell (for instance bash, dash, zsh)
  • SSH server

4.2. Install cdist

You can install cdist either from git or as a python package.

4.2.1. 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:

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.

You can also get cdist from github mirror.

To install cdist with distutils from cloned repository, first you have to create version.py:

./bin/build-helper version

Then you install it with:

make install

or with:

make install-user

to install it into user site-packages directory. Or directly with distutils:

python setup.py install

Note that bin/build-helper script is intended for cdist maintainers.

4.2.1.1. 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

# 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

git checkout -b 4.1 origin/4.1

4.2.1.2. Building and using documentation (man and html)

If you want to build and use the documentation, run:

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:

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:

make man

for only html documentation run:

make html

You can also build man pages for types in your ~/.cdist directory:

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:

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.

4.2.2. Python package

Cdist is available as a python package at PyPi. You can install it using

pip install cdist