78 lines
2.2 KiB
ReStructuredText
78 lines
2.2 KiB
ReStructuredText
Explorer
|
|
========
|
|
|
|
Description
|
|
-----------
|
|
Explorers are small scripts, typically written in POSIX shell,
|
|
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.
|
|
|
|
.. tip::
|
|
An :program:`explorer` can be written in **any scripting language**,
|
|
provided it is executable and has a proper **shebang**.
|
|
|
|
Nevertheless, for explorers, it is usually best to stick with the
|
|
**POSIX shell** in order to minimize
|
|
requirements on target hosts where they would need to be executed.
|
|
|
|
For executable shell code, the recommended shebang is :code:`#!/bin/sh -e`.
|
|
|
|
If an :program:`explorer` lacks `execute` permissions,
|
|
:program:`cdist` assumes it to be written in **shell** and executes it using
|
|
`$CDIST_REMOTE_SHELL`, which defaults to :code:`/bin/sh -e`.
|
|
|
|
For more details and examples, see :doc:`cdist-polyglot`.
|
|
|
|
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:
|
|
|
|
.. code-block:: sh
|
|
|
|
#!/bin/sh -e
|
|
|
|
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
|
|
|
|
#!/bin/sh -e
|
|
|
|
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
|