| 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 |