| 1 |
How to install cdist |
| 2 |
==================== |
| 3 |
|
| 4 |
Requirements |
| 5 |
------------- |
| 6 |
|
| 7 |
Source Host |
| 8 |
~~~~~~~~~~~ |
| 9 |
|
| 10 |
This is the machine from which you will configure target hosts. |
| 11 |
|
| 12 |
* /bin/sh: A POSIX like shell (for instance bash, dash, zsh) |
| 13 |
* Python >= 3.5 |
| 14 |
* SSH client |
| 15 |
* sphinx with the rtd theme (for building html docs and/or the man pages) |
| 16 |
|
| 17 |
Target Hosts |
| 18 |
~~~~~~~~~~~~ |
| 19 |
|
| 20 |
* /bin/sh: A POSIX like shell (for instance bash, dash, zsh) |
| 21 |
* SSH server |
| 22 |
|
| 23 |
Install cdist |
| 24 |
------------- |
| 25 |
|
| 26 |
From git |
| 27 |
~~~~~~~~ |
| 28 |
|
| 29 |
Cloning cdist from git gives you the advantage of having |
| 30 |
a version control in place for development of your own stuff |
| 31 |
immediately. |
| 32 |
|
| 33 |
To install cdist, execute the following commands: |
| 34 |
|
| 35 |
.. code-block:: sh |
| 36 |
|
| 37 |
git clone https://code.ungleich.ch/ungleich-public/cdist.git |
| 38 |
cd cdist |
| 39 |
export PATH=$PATH:$(pwd -P)/bin |
| 40 |
|
| 41 |
From version 4.2.0 cdist tags and releases are signed. |
| 42 |
You can get GPG public key used for signing `here <_static/pgp-key-EFD2AE4EC36B6901.asc>`_. |
| 43 |
It is assumed that you are familiar with *git* ways of signing and verification. |
| 44 |
|
| 45 |
You can also get cdist from `github mirror <https://github.com/ungleich/cdist>`_. |
| 46 |
|
| 47 |
To install cdist with distutils from cloned repository, first you have to |
| 48 |
create version.py: |
| 49 |
|
| 50 |
.. code-block:: sh |
| 51 |
|
| 52 |
./bin/cdist-build-helper version |
| 53 |
|
| 54 |
Then you install it with: |
| 55 |
|
| 56 |
.. code-block:: sh |
| 57 |
|
| 58 |
make install |
| 59 |
|
| 60 |
or with: |
| 61 |
|
| 62 |
.. code-block:: sh |
| 63 |
|
| 64 |
make install-user |
| 65 |
|
| 66 |
to install it into user *site-packages* directory. |
| 67 |
Or directly with distutils: |
| 68 |
|
| 69 |
.. code-block:: sh |
| 70 |
|
| 71 |
python setup.py install |
| 72 |
|
| 73 |
Note that `bin/cdist-build-helper` script is intended for cdist maintainers. |
| 74 |
|
| 75 |
|
| 76 |
Available versions in git |
| 77 |
^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 78 |
|
| 79 |
* The active development takes place in the **master** branch |
| 80 |
* The released versions can be found in the tags |
| 81 |
|
| 82 |
Other branches may be available for features or bugfixes, but they |
| 83 |
may vanish at any point. To select a specific branch use |
| 84 |
|
| 85 |
.. code-block:: sh |
| 86 |
|
| 87 |
# Generic code |
| 88 |
git checkout -b <localbranchname> origin/<branchname> |
| 89 |
|
| 90 |
So for instance if you want to use and stay with version 4.1, you can use |
| 91 |
|
| 92 |
.. code-block:: sh |
| 93 |
|
| 94 |
git checkout -b 4.1 origin/4.1 |
| 95 |
|
| 96 |
Building and using documentation (man and html) |
| 97 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 98 |
|
| 99 |
If you want to build and use the documentation, run: |
| 100 |
|
| 101 |
.. code-block:: sh |
| 102 |
|
| 103 |
make docs |
| 104 |
|
| 105 |
Documentation comes in two formats, man pages and full HTML |
| 106 |
documentation. Documentation is built into distribution's |
| 107 |
docs/dist directory. man pages are in docs/dist/man and |
| 108 |
HTML documentation in docs/dist/html. |
| 109 |
|
| 110 |
If you want to use man pages, run: |
| 111 |
|
| 112 |
.. code-block:: sh |
| 113 |
|
| 114 |
export MANPATH=$MANPATH:$(pwd -P)/docs/dist/man |
| 115 |
|
| 116 |
Or you can move man pages from docs/dist/man directory to some |
| 117 |
other directory and add it to MANPATH. |
| 118 |
|
| 119 |
Full HTML documentation can be accessed at docs/dist/html/index.html. |
| 120 |
|
| 121 |
You can also build only man pages or only html documentation, for |
| 122 |
only man pages run: |
| 123 |
|
| 124 |
.. code-block:: sh |
| 125 |
|
| 126 |
make man |
| 127 |
|
| 128 |
for only html documentation run: |
| 129 |
|
| 130 |
.. code-block:: sh |
| 131 |
|
| 132 |
make html |
| 133 |
|
| 134 |
You can also build man pages for types in your ~/.cdist directory: |
| 135 |
|
| 136 |
.. code-block:: sh |
| 137 |
|
| 138 |
make dotman |
| 139 |
|
| 140 |
Built man pages are now in docs/dist/man directory. If you have |
| 141 |
some other custom .cdist directory, e.g. /opt/cdist then use: |
| 142 |
|
| 143 |
.. code-block:: sh |
| 144 |
|
| 145 |
make DOT_CDIST_PATH=/opt/cdist dotman |
| 146 |
|
| 147 |
Note that `dotman`-target has to be built before a `make docs`-run, otherwise |
| 148 |
the custom man-pages are not picked up. |
| 149 |
|
| 150 |
Python package |
| 151 |
~~~~~~~~~~~~~~ |
| 152 |
|
| 153 |
Cdist is available as a python package at |
| 154 |
`PyPi <http://pypi.python.org/pypi/cdist/>`_. You can install it using |
| 155 |
|
| 156 |
.. code-block:: sh |
| 157 |
|
| 158 |
pip install cdist |
| 159 |
|
| 160 |
Installing from source with signature verification |
| 161 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 162 |
|
| 163 |
If you want to install cdist from signed source and verify it, first you need to |
| 164 |
download cdist archive and its detached signature. |
| 165 |
|
| 166 |
Get both, *cdist-x.y.z.tar.gz* and *cdist-x.y.z.tar.gz.asc* from release |
| 167 |
notes of the desired tag *x.y.z* at |
| 168 |
`cdist git repository <https://code.ungleich.ch/ungleich-public/cdist/-/tags>`_. |
| 169 |
|
| 170 |
Get GPG public key used for signing `here <_static/pgp-key-EFD2AE4EC36B6901.asc>`_ |
| 171 |
and import it into GPG. |
| 172 |
|
| 173 |
Now cdist source archive can be verified using `gpg`, e.g. to verify `cdist-6.2.0`: |
| 174 |
|
| 175 |
.. code-block:: sh |
| 176 |
|
| 177 |
$ gpg --verify cdist-6.2.0.tar.gz.asc cdist-6.2.0.targ.gz |
| 178 |
gpg: Signature made Sat Nov 30 23:14:19 2019 CET |
| 179 |
gpg: using RSA key 69767822F3ECC3C349C1EFFFEFD2AE4EC36B6901 |
| 180 |
gpg: Good signature from "ungleich GmbH (ungleich FOSS) <[email protected]>" [ultimate] |
| 181 |
|
| 182 |
Further steps are the same as for `installing from git <cdist-install.html#from-git>`_. |