Debian Codegraph @

docs/src/cdist-explorer.rst

raw
1 Explorer
2 ========
3
4 Description
5 -----------
6 Explorers are small shell scripts, which will be executed on the target
7 host. The aim of each explorer is to give hints to types on how to act on the
8 target system. An explorer outputs the result to stdout, which is usually
9 a one liner, but may be empty or multi line especially in the case of
10 type explorers.
11
12 There are general explorers, which are run in an early stage, and
13 type explorers. Both work almost exactly the same way, with the difference
14 that the values of the general explorers are stored in a general location and
15 the type specific below the object.
16
17 Explorers can reuse other explorers on the target system by calling
18
19 ::
20
21 $__explorer/<explorer_name> (general and type explorer)
22
23 or
24
25 ::
26
27 $__type_explorer/<explorer name> (type explorer).
28
29 In case of significant errors, the explorer may exit non-zero and return an
30 error message on stderr, which will cause cdist to abort.
31
32 You can also use stderr for debugging purposes while developing a new
33 explorer.
34
35 Examples
36 --------
37 A very simple explorer may look like this::
38
39 hostname
40
41 Which is in practise the **hostname** explorer.
42
43 A type explorer, which could check for the status of a package may look like this:
44
45 .. code-block:: sh
46
47 if [ -f "$__object/parameter/name" ]; then
48 name="$(cat "$__object/parameter/name")"
49 else
50 name="$__object_id"
51 fi
52
53 # Expect dpkg failing, if package is not known / installed
54 dpkg -s "$name" 2>/dev/null || exit 0