Debian Codegraph @

docs/src/cdist-reference.rst.sh

raw
1 #!/bin/sh
2 #
3 # 2010-2014 Nico Schottelius (nico-cdist at schottelius.org)
4 # 2014 Daniel Heule (hda at sfs.biz)
5 #
6 # This file is part of cdist.
7 #
8 # cdist is free software: you can redistribute it and/or modify
9 # it under the terms of the GNU General Public License as published by
10 # the Free Software Foundation, either version 3 of the License, or
11 # (at your option) any later version.
12 #
13 # cdist is distributed in the hope that it will be useful,
14 # but WITHOUT ANY WARRANTY; without even the implied warranty of
15 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 # GNU General Public License for more details.
17 #
18 # You should have received a copy of the GNU General Public License
19 # along with cdist. If not, see <http://www.gnu.org/licenses/>.
20 #
21 #
22 # Generate manpage that lists available types
23 #
24
25 __cdist_pwd="$(pwd -P)"
26 __cdist_mydir="${0%/*}";
27 __cdist_abs_mydir="$(cd "$__cdist_mydir" && pwd -P)"
28 __cdist_myname=${0##*/};
29 __cdist_abs_myname="$__cdist_abs_mydir/$__cdist_myname"
30
31 filename="${__cdist_myname%.sh}"
32 dest="$__cdist_abs_mydir/$filename"
33
34 cd "$__cdist_abs_mydir"
35
36 exec > "$dest"
37 cat << eof
38 Reference
39 =========
40 Variable, path and type reference for cdist
41
42 Explorers
43 ---------
44 The following global explorers are available:
45
46 eof
47 (
48 cd ../../cdist/conf/explorer
49 for explorer in $(ls * | LC_ALL=C sort); do
50 echo "- $explorer"
51 done
52 )
53
54 cat << eof
55
56 Paths
57 -----
58 \$HOME/.cdist
59 The standard cdist configuration directory relative to your home directory.
60 This is usually the place you want to store your site specific configuration.
61
62 cdist/conf/
63 The distribution configuration directory.
64 This contains types and explorers to be used.
65
66 cdist/inventory/
67 The distribution inventory directory.
68 This path is relative to cdist installation directory.
69
70 cdist/preos/
71 The distribution PreOS plugins directory.
72
73 confdir
74 Cdist will use all available configuration directories and create
75 a temporary confdir containing links to the real configuration directories.
76 This way it is possible to merge configuration directories.
77 By default it consists of everything in \$HOME/.cdist and cdist/conf/.
78 For more details see cdist(1).
79
80 confdir/files/
81 Cdist does not care about this directory besides providing access to it.
82 It is thought to be a general file storage area.
83
84 confdir/manifest/init
85 This is the central entry point.
86 It is an executable (+x bit set) shell script that can use
87 values from the explorers to decide which configuration to create
88 for the specified target host.
89 Its intent is to used to define mapping from configurations to hosts.
90
91 confdir/manifest/*
92 All other files in this directory are not directly used by cdist, but you
93 can separate configuration mappings, if you have a lot of code in the
94 conf/manifest/init file. This may also be helpful to have different admins
95 maintain different groups of hosts.
96
97 confdir/explorer/<name>
98 Contains explorers to be run on the target hosts, see \`cdist explorer <cdist-explorer.html>\`_.
99
100 confdir/type/
101 Contains all available types, which are used to provide
102 some kind of functionality. See \`cdist type <cdist-type.html>\`_.
103
104 confdir/type/<name>/
105 Home of the type <name>.
106 This directory is referenced by the variable __type (see below).
107
108 confdir/type/<name>/man.rst
109 Manpage in reStructuredText format (required for inclusion into upstream).
110
111 confdir/type/<name>/manifest
112 Used to generate additional objects from a type.
113
114 confdir/type/<name>/gencode-local
115 Used to generate code to be executed on the source host.
116
117 confdir/type/<name>/gencode-remote
118 Used to generate code to be executed on the target host.
119
120 confdir/type/<name>/parameter/required
121 Parameters required by type, \n separated list.
122
123 confdir/type/<name>/parameter/optional
124 Parameters optionally accepted by type, \n separated list.
125
126 confdir/type/<name>/parameter/default/*
127 Default values for optional parameters.
128 Assuming an optional parameter name of 'foo', it's default value would
129 be read from the file confdir/type/<name>/parameter/default/foo.
130
131 confdir/type/<name>/parameter/boolean
132 Boolean parameters accepted by type, \n separated list.
133
134 confdir/type/<name>/explorer
135 Location of the type specific explorers.
136 This directory is referenced by the variable __type_explorer (see below).
137 See \`cdist explorer <cdist-explorer.html>\`_.
138
139 confdir/type/<name>/files
140 This directory is reserved for user data and will not be used
141 by cdist at any time. It can be used for storing supplementary
142 files (like scripts to act as a template or configuration files).
143
144 out/
145 This directory contains output of cdist and is usually located
146 in a temporary directory and thus will be removed after the run.
147 This directory is referenced by the variable __global (see below).
148
149 out/explorer
150 Output of general explorers.
151
152 out/object
153 Objects created for the host.
154
155 out/object/<object>
156 Contains all object specific information.
157 This directory is referenced by the variable __object (see below).
158
159 out/object/<object>/explorers
160 Output of type specific explorers, per object.
161
162 Types
163 -----
164 The following types are available:
165
166 eof
167
168 # If there is no such file then ls prints error to stderr,
169 # so redirect stderr to /dev/null.
170 for type in $(ls man7/cdist-type__*.rst 2>/dev/null | LC_ALL=C sort); do
171 no_dir="${type#man7/}";
172 no_type="${no_dir#cdist-type}";
173 name="${no_type%.rst}";
174 manref="${no_dir%.rst}"
175 man="${manref}(7)"
176
177 echo "- $name" "(\`${man} <man7/${manref}.html>\`_)"
178 done
179
180 cat << eof
181
182
183 Objects
184 -------
185 For object to object communication and tests, the following paths are
186 usable within a object directory:
187
188 files
189 This directory is reserved for user data and will not be used
190 by cdist at any time. It can be used freely by the type
191 (for instance to store template results).
192 changed
193 This empty file exists in an object directory, if the object has
194 code to be executed (either remote or local).
195 stdin
196 This file exists and contains data, if data was provided on stdin
197 when the type was called.
198
199
200 Environment variables (for reading)
201 -----------------------------------
202 The following environment variables are exported by cdist:
203
204 __cdist_log_level, __cdist_log_level_name
205 cdist log level value and cdist log level name. One of:
206
207 +----------------+-----------------+
208 | Log level name | Log level value |
209 +================+=================+
210 | OFF | 60 |
211 +----------------+-----------------+
212 | ERROR | 40 |
213 +----------------+-----------------+
214 | WARNING | 30 |
215 +----------------+-----------------+
216 | INFO | 20 |
217 +----------------+-----------------+
218 | VERBOSE | 15 |
219 +----------------+-----------------+
220 | DEBUG | 10 |
221 +----------------+-----------------+
222 | TRACE | 5 |
223 +----------------+-----------------+
224
225 Available for: initial manifest, explorer, type manifest, type explorer,
226 type gencode.
227 __cdist_colored_log
228 whether or not cdist's log has colors enabled.
229 Is set to the string ``true`` if cdist's output is using colors,
230 otherwise the variable contains the string ``false``.
231
232 Available for: initial manifest, explorer, type manifest, type explorer,
233 type gencode.
234 __cdist_dry_run
235 Is set only when doing dry run (``-n`` flag).
236
237 Available for: initial manifest, explorer, type manifest, type explorer,
238 type gencode.
239 __explorer
240 Directory that contains all global explorers.
241
242 Available for: initial manifest, explorer, type explorer, shell.
243 __files
244 Directory that contains content from the "files" subdirectories
245 from the configuration directories.
246
247 Available for: initial manifest, type manifest, type gencode, shell.
248 __manifest
249 Directory that contains the initial manifest.
250
251 Available for: initial manifest, type manifest, shell.
252 __global
253 Directory that contains generic output like explorer.
254
255 Available for: initial manifest, type manifest, type gencode, shell.
256 __messages_in
257 File to read messages from.
258
259 Available for: initial manifest, type manifest, type gencode.
260 __messages_out
261 File to write messages.
262
263 Available for: initial manifest, type manifest, type gencode.
264 __object
265 Directory that contains the current object.
266
267 Available for: type manifest, type explorer, type gencode and code scripts.
268 __object_id
269 The type unique object id.
270
271 Available for: type manifest, type explorer, type gencode and code scripts.
272
273 | Note: The leading and the trailing "/" will always be stripped (caused by
274 the filesystem database and ensured by the core).
275 | Note: Double slashes ("//") will not be fixed and result in an error.
276 __object_name
277 The full qualified name of the current object.
278
279 Available for: type manifest, type explorer, type gencode.
280 __target_host
281 The host we are deploying to. This is primary variable. It's content is
282 literally the one user passed in.
283
284 Available for: explorer, initial manifest, type explorer, type manifest, type gencode, shell.
285 __target_hostname
286 The hostname of host we are deploying to. This variable is derived from
287 **__target_host** (using **socket.getaddrinfo(__target_host)** and then
288 **socket.gethostbyaddr()**).
289
290 Available for: explorer, initial manifest, type explorer, type manifest, type gencode, shell.
291 __target_fqdn
292 The fully qualified domain name of the host we are deploying to.
293 This variable is derived from **__target_host**
294 (using **socket.getfqdn()**).
295
296 Available for: explorer, initial manifest, type explorer, type manifest, type gencode, shell.
297 __target_host_tags
298 Comma separated list of target host tags.
299
300 Available for: explorer, initial manifest, type explorer, type manifest, type gencode, shell.
301 __type
302 Path to the current type.
303
304 Available for: type manifest, type gencode.
305 __type_explorer
306 Directory that contains the type explorers.
307
308 Available for: type explorer.
309
310 Environment variables (for writing)
311 -----------------------------------
312 The following environment variables influence the behaviour of cdist:
313
314 require
315 Setup dependencies between objects (see \`cdist manifest <cdist-manifest.html>\`_).
316
317 __cdist_log_level
318 cdist log level value. One of:
319
320 +----------------+-----------------+
321 | Log level | Log level value |
322 +================+=================+
323 | OFF | 60 |
324 +----------------+-----------------+
325 | ERROR | 40 |
326 +----------------+-----------------+
327 | WARNING | 30 |
328 +----------------+-----------------+
329 | INFO | 20 |
330 +----------------+-----------------+
331 | VERBOSE | 15 |
332 +----------------+-----------------+
333 | DEBUG | 10 |
334 +----------------+-----------------+
335 | TRACE | 5 |
336 +----------------+-----------------+
337
338 If set cdist will set this log level in
339 accordance with configuration rules. If cdist invokation is used
340 in types then nested cdist will honor this specified log level if
341 not specified otherwise while invoking it.
342
343 CDIST_PATH
344 Colon delimited list of config directories.
345
346 CDIST_LOCAL_SHELL
347 Use this shell locally instead of /bin/sh to execute scripts.
348
349 CDIST_REMOTE_SHELL
350 Use this shell remotely instead of /bin/sh to execute scripts.
351
352 CDIST_OVERRIDE
353 Allow overwriting type parameters (see \`cdist manifest <cdist-manifest.html>\`_).
354
355 CDIST_ORDER_DEPENDENCY
356 Create dependencies based on the execution order (see \`cdist manifest <cdist-manifest.html>\`_).
357 Note that in version 6.2.0 semantic of this processing mode is finally fixed and well defined.
358
359 CDIST_REMOTE_EXEC
360 Use this command for remote execution (should behave like ssh).
361
362 CDIST_REMOTE_COPY
363 Use this command for remote copy (should behave like scp).
364
365 CDIST_INVENTORY_DIR
366 Use this directory as inventory directory.
367
368 CDIST_BETA
369 Enable beta functionalities.
370
371 CDIST_COLORED_OUTPUT
372 Colorize cdist's output. If enabled, cdist will use different colors for
373 different log levels.
374 Recognized values are 'always', 'never', and 'auto' (the default).
375
376 CDIST_CACHE_PATH_PATTERN
377 Custom cache path pattern.
378 eof