14 changed files with 104 additions and 448 deletions
@ -1,11 +1,32 @@
|
||||
Documentation |
||||
============= |
||||
|
||||
.. toctree:: |
||||
:maxdepth: 1 |
||||
|
||||
cdist-manual |
||||
cdist contrib types <https://contrib.cdi.st> |
||||
cdist-os |
||||
cdist-speeches |
||||
cdist-changelog |
||||
Manuals |
||||
~~~~~~~ |
||||
|
||||
* You will find an **introduction** as well as a **full reference** in the `latest |
||||
cdist manual <manual/latest>`_. |
||||
* The community-maintained **'contrib' types** are documented on `their own |
||||
manual <manual/contrib>`_. |
||||
* Experimental features from the **beta** branch (i.e. cdist **trigger**, |
||||
**preos** and **scan**) are documented under the `beta manual |
||||
<manual/beta>`_. |
||||
* Depending how you installed cdist, type manuals might also be availale via |
||||
the ``man`` command (e.g. ``man 7 cdist-type__file``). |
||||
* Manual for previous releases can be found on the `manual archives page |
||||
<cdist-manual-archives.html>`_. |
||||
|
||||
Changelog |
||||
~~~~~~~~~ |
||||
|
||||
You will find the full changelog `here <cdist-changelog.html>`_. |
||||
|
||||
Talks |
||||
~~~~~ |
||||
|
||||
* `2013-11-22_eth_linux_erfa <speeches/2013-11-22_eth_linux_erfa.pdf>`_ |
||||
* `2014-05-08_linuxtag_berlin <speeches/2014-05-08_linuxtag_berlin.pdf>`_ |
||||
* `2014-05-19_cdi.st-zkb_linux_erfa <speeches/2014-05-19_cdi.st-zkb_linux_erfa.pdf>`_ |
||||
* `2014-06-10_openclouddays_teaser <speeches/2014-06-10_openclouddays_teaser.pdf>`_ |
||||
* `2014-11-07_sfs_linux_erfa_cdist_web_prototype <speeches/2014-11-07_sfs_linux_erfa_cdist_web_prototype.pdf>`_ |
||||
* `2014-11-07_sfs_linux_erfa_cdist4 <speeches/2014-11-07_sfs_linux_erfa_cdist4.pdf>`_ |
||||
|
||||
@ -1,167 +0,0 @@
|
||||
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.5 |
||||
* 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, as usual, you execute the following command: |
||||
|
||||
.. code-block:: sh |
||||
|
||||
python setup.py install |
||||
|
||||
|
||||
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>`_. |
||||
@ -1,10 +1,5 @@
|
||||
cdist manual |
||||
============ |
||||
|
||||
* `Latest manual <manual/latest>`_ |
||||
|
||||
* Checking out **beta** branch, i.e. cdist **trigger** and **preos** functionality? |
||||
Find the manual `here <manual/beta>`_. |
||||
cdist manual archives |
||||
===================== |
||||
|
||||
**All versions** |
||||
|
||||
@ -1,19 +0,0 @@
|
||||
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>`_ |
||||
@ -1,9 +0,0 @@
|
||||
Speeches |
||||
======== |
||||
|
||||
* `2013-11-22_eth_linux_erfa <speeches/2013-11-22_eth_linux_erfa.pdf>`_ |
||||
* `2014-05-08_linuxtag_berlin <speeches/2014-05-08_linuxtag_berlin.pdf>`_ |
||||
* `2014-05-19_cdi.st-zkb_linux_erfa <speeches/2014-05-19_cdi.st-zkb_linux_erfa.pdf>`_ |
||||
* `2014-06-10_openclouddays_teaser <speeches/2014-06-10_openclouddays_teaser.pdf>`_ |
||||
* `2014-11-07_sfs_linux_erfa_cdist_web_prototype <speeches/2014-11-07_sfs_linux_erfa_cdist_web_prototype.pdf>`_ |
||||
* `2014-11-07_sfs_linux_erfa_cdist4 <speeches/2014-11-07_sfs_linux_erfa_cdist4.pdf>`_ |
||||
@ -1,31 +0,0 @@
|
||||
Support |
||||
------- |
||||
|
||||
Chat |
||||
~~~~ |
||||
Matrix: ``#cdist:ungleich.ch`` |
||||
|
||||
IRC: ``#cdist`` @ `libera <https://libera.chat>`_ |
||||
|
||||
Matrix and IRC are bridged. |
||||
|
||||
|
||||
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/>`_. |
||||
@ -1,188 +0,0 @@
|
||||
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 |
||||
Loading…
Reference in new issue