| 1 |
cdist(1) |
| 2 |
======== |
| 3 |
|
| 4 |
NAME |
| 5 |
---- |
| 6 |
cdist - Usable Configuration Management |
| 7 |
|
| 8 |
|
| 9 |
SYNOPSIS |
| 10 |
-------- |
| 11 |
|
| 12 |
:: |
| 13 |
|
| 14 |
cdist [-h] [-V] {banner,config,install,inventory,preos,shell,info} ... |
| 15 |
|
| 16 |
cdist banner [-h] [-l LOGLEVEL] [-q] [-v] |
| 17 |
|
| 18 |
cdist config [-h] [-l LOGLEVEL] [-q] [-v] [-b] [--colors WHEN] |
| 19 |
[-g CONFIG_FILE] [-4] [-6] [-C CACHE_PATH_PATTERN] |
| 20 |
[-c CONF_DIR] [-i MANIFEST] [-j [JOBS]] [--log-server] |
| 21 |
[-n] [-o OUT_PATH] [-P] [-R [{tar,tgz,tbz2,txz}]] |
| 22 |
[-r REMOTE_OUT_PATH] [--remote-copy REMOTE_COPY] |
| 23 |
[--remote-exec REMOTE_EXEC] [-S] [-I INVENTORY_DIR] [-A] |
| 24 |
[-a] [-f HOSTFILE] [-p [HOST_MAX]] [-s] [-t] |
| 25 |
[host [host ...]] |
| 26 |
|
| 27 |
cdist install [-h] [-l LOGLEVEL] [-q] [-v] [-b] [--colors WHEN] |
| 28 |
[-g CONFIG_FILE] [-4] [-6] [-C CACHE_PATH_PATTERN] |
| 29 |
[-c CONF_DIR] [-i MANIFEST] [-j [JOBS]] [--log-server] |
| 30 |
[-n] [-o OUT_PATH] [-P] [-R [{tar,tgz,tbz2,txz}]] |
| 31 |
[-r REMOTE_OUT_PATH] [--remote-copy REMOTE_COPY] |
| 32 |
[--remote-exec REMOTE_EXEC] [-S] [-I INVENTORY_DIR] [-A] |
| 33 |
[-a] [-f HOSTFILE] [-p [HOST_MAX]] [-s] [-t] |
| 34 |
[host [host ...]] |
| 35 |
|
| 36 |
cdist inventory [-h] {add-host,add-tag,del-host,del-tag,list} ... |
| 37 |
|
| 38 |
cdist inventory add-host [-h] [-l LOGLEVEL] [-q] [-v] [-b] [--colors WHEN] |
| 39 |
[-g CONFIG_FILE] [-I INVENTORY_DIR] [-f HOSTFILE] |
| 40 |
[host [host ...]] |
| 41 |
|
| 42 |
cdist inventory add-tag [-h] [-l LOGLEVEL] [-q] [-v] [-b] [--colors WHEN] |
| 43 |
[-g CONFIG_FILE] [-I INVENTORY_DIR] [-f HOSTFILE] |
| 44 |
[-T TAGFILE] [-t TAGLIST] |
| 45 |
[host [host ...]] |
| 46 |
|
| 47 |
cdist inventory del-host [-h] [-l LOGLEVEL] [-q] [-v] [-b] [--colors WHEN] |
| 48 |
[-g CONFIG_FILE] [-I INVENTORY_DIR] [-a] |
| 49 |
[-f HOSTFILE] |
| 50 |
[host [host ...]] |
| 51 |
|
| 52 |
cdist inventory del-tag [-h] [-l LOGLEVEL] [-q] [-v] [-b] [--colors WHEN] |
| 53 |
[-g CONFIG_FILE] [-I INVENTORY_DIR] [-a] |
| 54 |
[-f HOSTFILE] [-T TAGFILE] [-t TAGLIST] |
| 55 |
[host [host ...]] |
| 56 |
|
| 57 |
cdist inventory list [-h] [-l LOGLEVEL] [-q] [-v] [-b] [--colors WHEN] |
| 58 |
[-g CONFIG_FILE] [-I INVENTORY_DIR] [-a] [-f HOSTFILE] |
| 59 |
[-H] [-t] |
| 60 |
[host [host ...]] |
| 61 |
|
| 62 |
cdist preos [-h] [-l LOGLEVEL] [-q] [-v] [-c CONF_DIR] [-g CONFIG_FILE] [-L] |
| 63 |
[preos] ... |
| 64 |
|
| 65 |
cdist preos [preos-options] debian [-h] [-l LOGLEVEL] [-q] [-v] [-b] [-a ARCH] [-B] |
| 66 |
[-C] [-c CDIST_PARAMS] [-D DRIVE] [-e REMOTE_EXEC] |
| 67 |
[-i MANIFEST] [-k KEYFILE ] [-m MIRROR] |
| 68 |
[-P ROOT_PASSWORD] [-p PXE_BOOT_DIR] [-r] |
| 69 |
[-S SCRIPT] [-s SUITE] [-y REMOTE_COPY] |
| 70 |
target_dir |
| 71 |
|
| 72 |
cdist preos [preos-options] devuan [-h] [-l LOGLEVEL] [-q] [-v] [-b] [-a ARCH] [-B] |
| 73 |
[-C] [-c CDIST_PARAMS] [-D DRIVE] [-e REMOTE_EXEC] |
| 74 |
[-i MANIFEST] [-k KEYFILE ] [-m MIRROR] |
| 75 |
[-P ROOT_PASSWORD] [-p PXE_BOOT_DIR] [-r] |
| 76 |
[-S SCRIPT] [-s SUITE] [-y REMOTE_COPY] |
| 77 |
target_dir |
| 78 |
|
| 79 |
cdist preos [preos-options] ubuntu [-h] [-l LOGLEVEL] [-q] [-v] [-b] [-a ARCH] [-B] |
| 80 |
[-C] [-c CDIST_PARAMS] [-D DRIVE] [-e REMOTE_EXEC] |
| 81 |
[-i MANIFEST] [-k KEYFILE ] [-m MIRROR] |
| 82 |
[-P ROOT_PASSWORD] [-p PXE_BOOT_DIR] [-r] |
| 83 |
[-S SCRIPT] [-s SUITE] [-y REMOTE_COPY] |
| 84 |
target_dir |
| 85 |
|
| 86 |
cdist shell [-h] [-l LOGLEVEL] [-q] [-v] [--colors WHEN] [-s SHELL] |
| 87 |
|
| 88 |
cdist info [-h] [-a] [-c CONF_DIR] [-e] [-F] [-f] [-g CONFIG_FILE] [-t] |
| 89 |
[pattern] |
| 90 |
|
| 91 |
cdist scan -I INTERFACE [--m MODE] [--name-mapper PATH_TO_SCRIPT] [--list] |
| 92 |
[-d CONFIG_DELAY] [-t TRIGGER_DELAY] |
| 93 |
|
| 94 |
|
| 95 |
DESCRIPTION |
| 96 |
----------- |
| 97 |
cdist is the frontend executable to the cdist configuration management. |
| 98 |
It supports different subcommands as explained below. |
| 99 |
|
| 100 |
It is written in Python so it requires :strong:`python`\ (1) to be installed. |
| 101 |
It requires a minimal Python version 3.5. |
| 102 |
|
| 103 |
GENERAL |
| 104 |
------- |
| 105 |
All commands accept the following options: |
| 106 |
|
| 107 |
**-h, --help** |
| 108 |
Show the help screen. |
| 109 |
|
| 110 |
**--colors WHEN** |
| 111 |
Colorize cdist's output. If enabled, cdist will use different colors for |
| 112 |
different log levels. |
| 113 |
WHEN recognizes the values 'always', 'never', and 'auto' (the default). |
| 114 |
|
| 115 |
If the value is 'auto', colored output is enabled if stdout is a TTY |
| 116 |
unless the NO_COLOR (https://no-color.org/) environment variable is defined. |
| 117 |
|
| 118 |
**-l LOGLEVEL, --log-level LOGLEVEL** |
| 119 |
Set the specified verbosity level. The levels, in |
| 120 |
order from the lowest to the highest, are: ERROR (-1), |
| 121 |
WARNING (0), INFO (1), VERBOSE (2), DEBUG (3), TRACE (4 |
| 122 |
or higher). If used along with -v then -v increases |
| 123 |
last set value and -l overwrites last set value. |
| 124 |
|
| 125 |
**-q, --quiet** |
| 126 |
Quiet mode: disables logging, including WARNING and ERROR. |
| 127 |
|
| 128 |
**-v, --verbose** |
| 129 |
Increase the verbosity level. Every instance of -v |
| 130 |
increments the verbosity level by one. Its default |
| 131 |
value is 0 which includes ERROR and WARNING levels. |
| 132 |
The levels, in order from the lowest to the highest, |
| 133 |
are: ERROR (-1), WARNING (0), INFO (1), VERBOSE (2), |
| 134 |
DEBUG (3), TRACE (4 or higher). If used along with -l |
| 135 |
then -l overwrites last set value and -v increases |
| 136 |
last set value. |
| 137 |
|
| 138 |
**-V, --version** |
| 139 |
Show version and exit. |
| 140 |
|
| 141 |
|
| 142 |
BANNER |
| 143 |
------ |
| 144 |
Displays the cdist banner. Useful for printing |
| 145 |
cdist posters - a must have for every office. |
| 146 |
|
| 147 |
|
| 148 |
CONFIG/INSTALL |
| 149 |
-------------- |
| 150 |
Configure/install one or more hosts. |
| 151 |
Install command is currently in beta. |
| 152 |
|
| 153 |
**-4, --force-ipv4** |
| 154 |
Force to use IPv4 addresses only. No influence for |
| 155 |
custom remote commands. |
| 156 |
|
| 157 |
**-6, --force-ipv6** |
| 158 |
Force to use IPv6 addresses only. No influence for |
| 159 |
custom remote commands. |
| 160 |
|
| 161 |
**-A, --all-tagged** |
| 162 |
Use all hosts present in tags db. Currently in beta. |
| 163 |
|
| 164 |
**-a, --all** |
| 165 |
List hosts that have all specified tags, if -t/--tag |
| 166 |
is specified. |
| 167 |
|
| 168 |
**-b, --beta** |
| 169 |
Enable beta functionality. |
| 170 |
|
| 171 |
**-C CACHE_PATH_PATTERN, --cache-path-pattern CACHE_PATH_PATTERN** |
| 172 |
Specify custom cache path pattern. If it is not set then |
| 173 |
default hostdir is used. For more info on format see |
| 174 |
:strong:`CACHE PATH PATTERN FORMAT` below. |
| 175 |
|
| 176 |
**-c CONF_DIR, --conf-dir CONF_DIR** |
| 177 |
Add a configuration directory. Can be specified multiple times. |
| 178 |
If configuration directories contain conflicting types, explorers or |
| 179 |
manifests, then the last one found is used. |
| 180 |
|
| 181 |
**-f HOSTFILE, --file HOSTFILE** |
| 182 |
Read specified file for a list of additional hosts to operate on |
| 183 |
or if '-' is given, read stdin (one host per line). For the file |
| 184 |
format see :strong:`HOSTFILE FORMAT` below. |
| 185 |
|
| 186 |
**-g CONFIG_FILE, --config-file CONFIG_FILE** |
| 187 |
Use specified custom configuration file. |
| 188 |
|
| 189 |
**-I INVENTORY_DIR, --inventory INVENTORY_DIR** |
| 190 |
Use specified custom inventory directory. Inventory |
| 191 |
directory is set up by the following rules: if cdist |
| 192 |
configuration resolves this value then specified |
| 193 |
directory is used, if HOME env var is set then |
| 194 |
~/.cdit/inventory is used, otherwise distribution |
| 195 |
inventory directory is used. |
| 196 |
|
| 197 |
**-i MANIFEST, --initial-manifest MANIFEST** |
| 198 |
Path to a cdist manifest or - to read from stdin. |
| 199 |
|
| 200 |
**-j [JOBS], --jobs [JOBS]** |
| 201 |
Operate in parallel in specified maximum number of |
| 202 |
jobs. Global explorers, object prepare and object run |
| 203 |
are supported. Without argument CPU count is used by |
| 204 |
default. |
| 205 |
|
| 206 |
**--log-server** |
| 207 |
Start a log server for sub processes to use. This is |
| 208 |
mainly useful when running cdist nested from a code- |
| 209 |
local script. Log server is always implicitly started |
| 210 |
for 'install' command. |
| 211 |
|
| 212 |
**-n, --dry-run** |
| 213 |
Do not execute code. |
| 214 |
|
| 215 |
**-o OUT_PATH, --out-dir OUT_PATH** |
| 216 |
Directory to save cdist output in. |
| 217 |
|
| 218 |
**-P, --timestamp** |
| 219 |
Timestamp log messages with the current local date and time |
| 220 |
in the format: YYYYMMDDHHMMSS.us. |
| 221 |
|
| 222 |
**-p [HOST_MAX], --parallel [HOST_MAX]** |
| 223 |
Operate on multiple hosts in parallel for specified |
| 224 |
maximum hosts at a time. Without argument CPU count is |
| 225 |
used by default. |
| 226 |
|
| 227 |
**-R [{tar,tgz,tbz2,txz}], --use-archiving [{tar,tgz,tbz2,txz}]** |
| 228 |
Operate by using archiving with compression where |
| 229 |
appropriate. Supported values are: tar - tar archive, |
| 230 |
tgz - gzip tar archive (the default), tbz2 - bzip2 tar |
| 231 |
archive and txz - lzma tar archive. Currently in beta. |
| 232 |
|
| 233 |
**-r REMOTE_OUT_PATH, --remote-out-dir REMOTE_OUT_PATH** |
| 234 |
Directory to save cdist output in on the target host. |
| 235 |
|
| 236 |
**-S, --disable-saving-output-streams** |
| 237 |
Disable saving output streams. |
| 238 |
|
| 239 |
**-s, --sequential** |
| 240 |
Operate on multiple hosts sequentially (default). |
| 241 |
|
| 242 |
**--remote-copy REMOTE_COPY** |
| 243 |
Command to use for remote copy (should behave like scp). |
| 244 |
|
| 245 |
**--remote-exec REMOTE_EXEC** |
| 246 |
Command to use for remote execution (should behave like ssh). |
| 247 |
|
| 248 |
**-t, --tag** |
| 249 |
Host is specified by tag, not hostname/address; list |
| 250 |
all hosts that contain any of specified tags. |
| 251 |
Currently in beta. |
| 252 |
|
| 253 |
HOSTFILE FORMAT |
| 254 |
~~~~~~~~~~~~~~~ |
| 255 |
The HOSTFILE contains one host per line. |
| 256 |
A comment is started with '#' and continues to the end of the line. |
| 257 |
Any leading and trailing whitespace on a line is ignored. |
| 258 |
Empty lines are ignored/skipped. |
| 259 |
|
| 260 |
|
| 261 |
The Hostfile lines are processed as follows. First, all comments are |
| 262 |
removed. Then all leading and trailing whitespace characters are stripped. |
| 263 |
If such a line results in empty line it is ignored/skipped. Otherwise, |
| 264 |
host string is used. |
| 265 |
|
| 266 |
CACHE PATH PATTERN FORMAT |
| 267 |
~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 268 |
Cache path pattern specifies path for a cache directory subdirectory. |
| 269 |
In the path, '%N' will be substituted by the target host, '%h' will |
| 270 |
be substituted by the calculated host directory, '%P' will be substituted |
| 271 |
by the current process id. All format codes that |
| 272 |
:strong:`python` :strong:`datetime.strftime()` function supports, except |
| 273 |
'%h', are supported. These date/time directives format cdist config/install |
| 274 |
start time. |
| 275 |
|
| 276 |
If empty pattern is specified then default calculated host directory |
| 277 |
is used. |
| 278 |
|
| 279 |
Calculated host directory is a hash of a host cdist operates on. |
| 280 |
|
| 281 |
Resulting path is used to specify cache path subdirectory under which |
| 282 |
current host cache data are saved. |
| 283 |
|
| 284 |
|
| 285 |
INVENTORY |
| 286 |
--------- |
| 287 |
Manage inventory database. |
| 288 |
Currently in beta with all sub-commands. |
| 289 |
|
| 290 |
|
| 291 |
INVENTORY ADD-HOST |
| 292 |
------------------ |
| 293 |
Add host(s) to inventory database. |
| 294 |
|
| 295 |
**host** |
| 296 |
Host(s) to add. |
| 297 |
|
| 298 |
**-b, --beta** |
| 299 |
Enable beta functionality. |
| 300 |
|
| 301 |
**-f HOSTFILE, --file HOSTFILE** |
| 302 |
Read additional hosts to add from specified file or |
| 303 |
from stdin if '-' (each host on separate line). |
| 304 |
Hostfile format is the same as config hostfile format. |
| 305 |
|
| 306 |
**-g CONFIG_FILE, --config-file CONFIG_FILE** |
| 307 |
Use specified custom configuration file. |
| 308 |
|
| 309 |
**-I INVENTORY_DIR, --inventory INVENTORY_DIR** |
| 310 |
Use specified custom inventory directory. Inventory |
| 311 |
directory is set up by the following rules: if cdist |
| 312 |
configuration resolves this value then specified |
| 313 |
directory is used, if HOME env var is set then |
| 314 |
~/.cdit/inventory is used, otherwise distribution |
| 315 |
inventory directory is used. |
| 316 |
|
| 317 |
|
| 318 |
INVENTORY ADD-TAG |
| 319 |
----------------- |
| 320 |
Add tag(s) to inventory database. |
| 321 |
|
| 322 |
**host** |
| 323 |
List of host(s) for which tags are added. |
| 324 |
|
| 325 |
**-b, --beta** |
| 326 |
Enable beta functionality. |
| 327 |
|
| 328 |
**-f HOSTFILE, --file HOSTFILE** |
| 329 |
Read additional hosts to add tags from specified file |
| 330 |
or from stdin if '-' (each host on separate line). |
| 331 |
Hostfile format is the same as config hostfile format. |
| 332 |
|
| 333 |
**-g CONFIG_FILE, --config-file CONFIG_FILE** |
| 334 |
Use specified custom configuration file. |
| 335 |
|
| 336 |
**-I INVENTORY_DIR, --inventory INVENTORY_DIR** |
| 337 |
Use specified custom inventory directory. Inventory |
| 338 |
directory is set up by the following rules: if cdist |
| 339 |
configuration resolves this value then specified |
| 340 |
directory is used, if HOME env var is set then |
| 341 |
~/.cdit/inventory is used, otherwise distribution |
| 342 |
inventory directory is used. |
| 343 |
|
| 344 |
**-T TAGFILE, --tag-file TAGFILE** |
| 345 |
Read additional tags to add from specified file or |
| 346 |
from stdin if '-' (each tag on separate line). |
| 347 |
Tagfile format is the same as config hostfile format. |
| 348 |
|
| 349 |
**-t TAGLIST, --taglist TAGLIST** |
| 350 |
Tag list to be added for specified host(s), comma |
| 351 |
separated values. |
| 352 |
|
| 353 |
|
| 354 |
INVENTORY DEL-HOST |
| 355 |
------------------ |
| 356 |
Delete host(s) from inventory database. |
| 357 |
|
| 358 |
**host** |
| 359 |
Host(s) to delete. |
| 360 |
|
| 361 |
**-a, --all** |
| 362 |
Delete all hosts. |
| 363 |
|
| 364 |
**-b, --beta** |
| 365 |
Enable beta functionality. |
| 366 |
|
| 367 |
**-f HOSTFILE, --file HOSTFILE** |
| 368 |
Read additional hosts to delete from specified file or |
| 369 |
from stdin if '-' (each host on separate line). |
| 370 |
Hostfile format is the same as config hostfile format. |
| 371 |
|
| 372 |
**-g CONFIG_FILE, --config-file CONFIG_FILE** |
| 373 |
Use specified custom configuration file. |
| 374 |
|
| 375 |
**-I INVENTORY_DIR, --inventory INVENTORY_DIR** |
| 376 |
Use specified custom inventory directory. Inventory |
| 377 |
directory is set up by the following rules: if cdist |
| 378 |
configuration resolves this value then specified |
| 379 |
directory is used, if HOME env var is set then |
| 380 |
~/.cdit/inventory is used, otherwise distribution |
| 381 |
inventory directory is used. |
| 382 |
|
| 383 |
|
| 384 |
INVENTORY DEL-TAG |
| 385 |
----------------- |
| 386 |
Delete tag(s) from inventory database. |
| 387 |
|
| 388 |
**host** |
| 389 |
List of host(s) for which tags are deleted. |
| 390 |
|
| 391 |
**-a, --all** |
| 392 |
Delete all tags for specified host(s). |
| 393 |
|
| 394 |
**-b, --beta** |
| 395 |
Enable beta functionality. |
| 396 |
|
| 397 |
**-f HOSTFILE, --file HOSTFILE** |
| 398 |
Read additional hosts to delete tags for from |
| 399 |
specified file or from stdin if '-' (each host on |
| 400 |
separate line). Hostfile format is the same as |
| 401 |
config hostfile format. |
| 402 |
|
| 403 |
**-g CONFIG_FILE, --config-file CONFIG_FILE** |
| 404 |
Use specified custom configuration file. |
| 405 |
|
| 406 |
**-I INVENTORY_DIR, --inventory INVENTORY_DIR** |
| 407 |
Use specified custom inventory directory. Inventory |
| 408 |
directory is set up by the following rules: if cdist |
| 409 |
configuration resolves this value then specified |
| 410 |
directory is used, if HOME env var is set then |
| 411 |
~/.cdit/inventory is used, otherwise distribution |
| 412 |
inventory directory is used. |
| 413 |
|
| 414 |
**-T TAGFILE, --tag-file TAGFILE** |
| 415 |
Read additional tags from specified file or from stdin |
| 416 |
if '-' (each tag on separate line). |
| 417 |
Tagfile format is the same as config hostfile format. |
| 418 |
|
| 419 |
**-t TAGLIST, --taglist TAGLIST** |
| 420 |
Tag list to be deleted for specified host(s), comma |
| 421 |
separated values. |
| 422 |
|
| 423 |
|
| 424 |
INVENTORY LIST |
| 425 |
-------------- |
| 426 |
List inventory database. |
| 427 |
|
| 428 |
**host** |
| 429 |
Host(s) to list. |
| 430 |
|
| 431 |
**-a, --all** |
| 432 |
List hosts that have all specified tags, if -t/--tag |
| 433 |
is specified. |
| 434 |
|
| 435 |
**-b, --beta** |
| 436 |
Enable beta functionality. |
| 437 |
|
| 438 |
**-f HOSTFILE, --file HOSTFILE** |
| 439 |
Read additional hosts to list from specified file or |
| 440 |
from stdin if '-' (each host on separate line). If no |
| 441 |
host or host file is specified then, by default, list |
| 442 |
all. Hostfile format is the same as config hostfile format. |
| 443 |
|
| 444 |
**-g CONFIG_FILE, --config-file CONFIG_FILE** |
| 445 |
Use specified custom configuration file. |
| 446 |
|
| 447 |
**-H, --host-only** |
| 448 |
Suppress tags listing. |
| 449 |
|
| 450 |
**-I INVENTORY_DIR, --inventory INVENTORY_DIR** |
| 451 |
Use specified custom inventory directory. Inventory |
| 452 |
directory is set up by the following rules: if cdist |
| 453 |
configuration resolves this value then specified |
| 454 |
directory is used, if HOME env var is set then |
| 455 |
~/.cdit/inventory is used, otherwise distribution |
| 456 |
inventory directory is used. |
| 457 |
|
| 458 |
**-t, --tag** |
| 459 |
Host is specified by tag, not hostname/address; list |
| 460 |
all hosts that contain any of specified tags. |
| 461 |
|
| 462 |
|
| 463 |
PREOS |
| 464 |
----- |
| 465 |
Create PreOS. |
| 466 |
|
| 467 |
**-c CONF_DIR, --conf-dir CONF_DIR** |
| 468 |
Add configuration directory (one that contains "preos" subdirectory). |
| 469 |
|
| 470 |
**-g CONFIG_FILE, --config-file CONFIG_FILE** |
| 471 |
Use specified custom configuration file. |
| 472 |
|
| 473 |
**-L, --list-preoses** |
| 474 |
List available PreOS-es. |
| 475 |
|
| 476 |
Currently, the following PreOS-es are supported: |
| 477 |
|
| 478 |
* debian |
| 479 |
* ubuntu |
| 480 |
* devuan |
| 481 |
|
| 482 |
|
| 483 |
PREOS DEBIAN/DEVUAN |
| 484 |
------------------- |
| 485 |
|
| 486 |
**target_dir** |
| 487 |
target directory where PreOS will be bootstrapped |
| 488 |
|
| 489 |
**-a ARCH, --arch ARCH** |
| 490 |
target debootstrap architecture, by default 'amd64' |
| 491 |
|
| 492 |
**-B, --bootstrap** |
| 493 |
do bootstrap step |
| 494 |
|
| 495 |
**-b, --beta** |
| 496 |
Enable beta functionality. |
| 497 |
|
| 498 |
**-C, --configure** |
| 499 |
do configure step |
| 500 |
|
| 501 |
**-c CDIST_PARAMS, --cdist-params CDIST_PARAMS** |
| 502 |
parameters that will be passed to cdist config, by |
| 503 |
default '-v' is used |
| 504 |
|
| 505 |
**-D DRIVE, --drive-boot DRIVE** |
| 506 |
create bootable PreOS on specified drive |
| 507 |
|
| 508 |
**-e REMOTE_EXEC, --remote-exec REMOTE_EXEC** |
| 509 |
remote exec that cdist config will use, by default |
| 510 |
internal script is used |
| 511 |
|
| 512 |
**-i MANIFEST, --init-manifest MANIFEST** |
| 513 |
init manifest that cdist config will use, by default |
| 514 |
internal init manifest is used |
| 515 |
|
| 516 |
**-k KEYFILE, --keyfile KEYFILE** |
| 517 |
ssh key files that will be added to cdist config; |
| 518 |
'``__ssh_authorized_keys root ...``' type is appended to initial manifest |
| 519 |
|
| 520 |
**-m MIRROR, --mirror MIRROR** |
| 521 |
use specified mirror for debootstrap |
| 522 |
|
| 523 |
**-P ROOT_PASSWORD, --root-password ROOT_PASSWORD** |
| 524 |
Set specified password for root, generated by default |
| 525 |
|
| 526 |
**-p PXE_BOOT_DIR, --pxe-boot-dir PXE_BOOT_DIR** |
| 527 |
PXE boot directory |
| 528 |
|
| 529 |
**-r, --rm-bootstrap-dir** |
| 530 |
remove target directory after finishing |
| 531 |
|
| 532 |
**-S SCRIPT, --script SCRIPT** |
| 533 |
use specified script for debootstrap |
| 534 |
|
| 535 |
**-s SUITE, --suite SUITE** |
| 536 |
suite used for debootstrap, by default 'stable' |
| 537 |
|
| 538 |
**-y REMOTE_COPY, --remote-copy REMOTE_COPY** |
| 539 |
remote copy that cdist config will use, by default |
| 540 |
internal script is used |
| 541 |
|
| 542 |
|
| 543 |
PREOS UBUNTU |
| 544 |
------------ |
| 545 |
|
| 546 |
**target_dir** |
| 547 |
target directory where PreOS will be bootstrapped |
| 548 |
|
| 549 |
**-a ARCH, --arch ARCH** |
| 550 |
target debootstrap architecture, by default 'amd64' |
| 551 |
|
| 552 |
**-B, --bootstrap** |
| 553 |
do bootstrap step |
| 554 |
|
| 555 |
**-b, --beta** |
| 556 |
Enable beta functionality. |
| 557 |
|
| 558 |
**-C, --configure** |
| 559 |
do configure step |
| 560 |
|
| 561 |
**-c CDIST_PARAMS, --cdist-params CDIST_PARAMS** |
| 562 |
parameters that will be passed to cdist config, by |
| 563 |
default '-v' is used |
| 564 |
|
| 565 |
**-D DRIVE, --drive-boot DRIVE** |
| 566 |
create bootable PreOS on specified drive |
| 567 |
|
| 568 |
**-e REMOTE_EXEC, --remote-exec REMOTE_EXEC** |
| 569 |
remote exec that cdist config will use, by default |
| 570 |
internal script is used |
| 571 |
|
| 572 |
**-i MANIFEST, --init-manifest MANIFEST** |
| 573 |
init manifest that cdist config will use, by default |
| 574 |
internal init manifest is used |
| 575 |
|
| 576 |
**-k KEYFILE, --keyfile KEYFILE** |
| 577 |
ssh key files that will be added to cdist config; |
| 578 |
'``__ssh_authorized_keys root ...``' type is appended to initial manifest |
| 579 |
|
| 580 |
**-m MIRROR, --mirror MIRROR** |
| 581 |
use specified mirror for debootstrap |
| 582 |
|
| 583 |
**-P ROOT_PASSWORD, --root-password ROOT_PASSWORD** |
| 584 |
Set specified password for root, generated by default |
| 585 |
|
| 586 |
**-p PXE_BOOT_DIR, --pxe-boot-dir PXE_BOOT_DIR** |
| 587 |
PXE boot directory |
| 588 |
|
| 589 |
**-r, --rm-bootstrap-dir** |
| 590 |
remove target directory after finishing |
| 591 |
|
| 592 |
**-S SCRIPT, --script SCRIPT** |
| 593 |
use specified script for debootstrap |
| 594 |
|
| 595 |
**-s SUITE, --suite SUITE** |
| 596 |
suite used for debootstrap, by default 'xenial' |
| 597 |
|
| 598 |
**-y REMOTE_COPY, --remote-copy REMOTE_COPY** |
| 599 |
remote copy that cdist config will use, by default |
| 600 |
internal script is used |
| 601 |
|
| 602 |
|
| 603 |
SHELL |
| 604 |
----- |
| 605 |
This command allows you to spawn a shell that enables access |
| 606 |
to the types as commands. It can be thought as an |
| 607 |
"interactive manifest" environment. See below for example |
| 608 |
usage. Its primary use is for debugging type parameters. |
| 609 |
|
| 610 |
**-s SHELL, --shell SHELL** |
| 611 |
Select shell to use, defaults to current shell. Used shell should |
| 612 |
be POSIX compatible shell. |
| 613 |
|
| 614 |
|
| 615 |
INFO |
| 616 |
---- |
| 617 |
Display information for cdist (global explorers, types). |
| 618 |
|
| 619 |
**pattern** |
| 620 |
Glob pattern. If it contains special characters('?', '*', '[') then it is |
| 621 |
used as specified, otherwise it is translated to `*pattern*`. |
| 622 |
|
| 623 |
**-h, --help** |
| 624 |
Show help message and exit. |
| 625 |
|
| 626 |
**-a, --all** |
| 627 |
Display all info. This is the default. |
| 628 |
|
| 629 |
**-c CONF_DIR, --conf-dir CONF_DIR** |
| 630 |
Add configuration directory (can be repeated). |
| 631 |
|
| 632 |
**-e, --global-explorers** |
| 633 |
Display info for global explorers. |
| 634 |
|
| 635 |
**-F, --fixed-string** |
| 636 |
Interpret pattern as a fixed string. |
| 637 |
|
| 638 |
**-f, --full** |
| 639 |
Display full details. |
| 640 |
|
| 641 |
**-g CONFIG_FILE, --config-file CONFIG_FILE** |
| 642 |
Use specified custom configuration file. |
| 643 |
|
| 644 |
**-t, --types** |
| 645 |
Display info for types. |
| 646 |
|
| 647 |
SCAN |
| 648 |
---- |
| 649 |
|
| 650 |
Runs cdist as a daemon that discover/watch on hosts and reconfigure them |
| 651 |
periodically. |
| 652 |
|
| 653 |
**-I INTERFACE, --interfaces INTERFACE** |
| 654 |
Interface to listen on. Can be specified multiple times. |
| 655 |
|
| 656 |
**-m MODE, --mode MODE** |
| 657 |
Scanner components to enable. Can be specified multiple time to enable more |
| 658 |
than one component. Supported modes are: scan, trigger and config. Defaults |
| 659 |
to tiggger and scan. |
| 660 |
|
| 661 |
**--name-mapper PATH_TO_SCRIPT** |
| 662 |
Path to script used to resolve a remote host name from an IPv6 address. |
| 663 |
|
| 664 |
**--list** |
| 665 |
List known hosts and exit. |
| 666 |
|
| 667 |
**-d CONFIG_DELAY, --config-delay CONFIG_DELAY** |
| 668 |
How long (seconds) to wait before reconfiguring after last try (config mode only). |
| 669 |
|
| 670 |
**-t TRIGGER_DELAY, --tigger-delay TRIGGER_DELAY** |
| 671 |
How long (seconds) to wait between ICMPv6 echo requests (trigger mode only). |
| 672 |
|
| 673 |
CONFIGURATION |
| 674 |
------------- |
| 675 |
cdist obtains configuration data from the following sources in the following |
| 676 |
order (from higher to lower precedence): |
| 677 |
|
| 678 |
#. command-line options |
| 679 |
#. configuration file specified at command-line |
| 680 |
#. configuration file specified in CDIST_CONFIG_FILE environment variable |
| 681 |
#. environment variables |
| 682 |
#. user's configuration file (first one found of ~/.cdist.cfg, $XDG_CONFIG_HOME/cdist/cdist.cfg, in specified order) |
| 683 |
#. system-wide configuration file (/etc/cdist.cfg). |
| 684 |
|
| 685 |
CONFIGURATION FILE FORMAT |
| 686 |
~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 687 |
cdist configuration file is in the INI file format. Currently it supports |
| 688 |
only [GLOBAL] section. |
| 689 |
The possible keywords and their meanings are as follows: |
| 690 |
|
| 691 |
:strong:`archiving` |
| 692 |
Use specified archiving. Valid values include: |
| 693 |
'none', 'tar', 'tgz', 'tbz2' and 'txz'. |
| 694 |
|
| 695 |
:strong:`beta` |
| 696 |
Enable beta functionality. It recognizes boolean values from |
| 697 |
'yes'/'no', 'on'/'off', 'true'/'false' and '1'/'0'. |
| 698 |
|
| 699 |
:strong:`cache_path_pattern` |
| 700 |
Specify cache path pattern. |
| 701 |
|
| 702 |
:strong:`colored_output` |
| 703 |
Colorize cdist's output. cf. the :code:`--colors` option. |
| 704 |
|
| 705 |
:strong:`conf_dir` |
| 706 |
List of configuration directories separated with the character conventionally |
| 707 |
used by the operating system to separate search path components (as in PATH), |
| 708 |
such as ':' for POSIX or ';' for Windows. |
| 709 |
If also specified at command line then values from command line are |
| 710 |
appended to this value. |
| 711 |
|
| 712 |
:strong:`init_manifest` |
| 713 |
Specify default initial manifest. |
| 714 |
|
| 715 |
:strong:`inventory_dir` |
| 716 |
Specify inventory directory. |
| 717 |
|
| 718 |
:strong:`jobs` |
| 719 |
Specify number of jobs for parallel processing. If -1 then the default, |
| 720 |
number of CPU's in the system is used. If 0 then parallel processing in |
| 721 |
jobs is disabled. If set to positive number then specified maximum |
| 722 |
number of processes will be used. |
| 723 |
|
| 724 |
:strong:`local_shell` |
| 725 |
Shell command used for local execution. |
| 726 |
|
| 727 |
:strong:`out_path` |
| 728 |
Directory to save cdist output in. |
| 729 |
|
| 730 |
:strong:`parallel` |
| 731 |
Process hosts in parallel. If -1 then the default, number of CPU's in |
| 732 |
the system is used. If 0 then parallel processing of hosts is disabled. |
| 733 |
If set to positive number then specified maximum number of processes |
| 734 |
will be used. |
| 735 |
|
| 736 |
:strong:`remote_copy` |
| 737 |
Command to use for remote copy (should behave like scp). |
| 738 |
|
| 739 |
:strong:`remote_exec` |
| 740 |
Command to use for remote execution (should behave like ssh). |
| 741 |
|
| 742 |
:strong:`remote_out_path` |
| 743 |
Directory to save cdist output in on the target host. |
| 744 |
|
| 745 |
:strong:`remote_shell` |
| 746 |
Shell command at remote host used for remote execution. |
| 747 |
|
| 748 |
:strong:`save_output_streams` |
| 749 |
Enable/disable saving output streams (enabled by default). |
| 750 |
It recognizes boolean values from 'yes'/'no', 'on'/'off', 'true'/'false' |
| 751 |
and '1'/'0'. |
| 752 |
|
| 753 |
:strong:`timestamp` |
| 754 |
Timestamp log messages with the current local date and time |
| 755 |
in the format: YYYYMMDDHHMMSS.us. |
| 756 |
|
| 757 |
:strong:`verbosity` |
| 758 |
Set verbosity level. Valid values are: |
| 759 |
'ERROR', 'WARNING', 'INFO', 'VERBOSE', 'DEBUG', 'TRACE' and 'OFF'. |
| 760 |
|
| 761 |
|
| 762 |
FILES |
| 763 |
----- |
| 764 |
~/.cdist |
| 765 |
Your personal cdist config directory. If exists it will be |
| 766 |
automatically used. |
| 767 |
~/.cdist/cache |
| 768 |
Local cache directory. |
| 769 |
~/.cdist/inventory |
| 770 |
The home inventory directory. If ~/.cdist exists it will be used as |
| 771 |
default inventory directory. |
| 772 |
~/.cdist/preos |
| 773 |
PreOS plugins directory, if existing. |
| 774 |
cdist/conf |
| 775 |
The distribution configuration directory. It contains official types and |
| 776 |
explorers. This path is relative to cdist installation directory. |
| 777 |
cdist/inventory |
| 778 |
The distribution inventory directory. |
| 779 |
This path is relative to cdist installation directory. |
| 780 |
cdist/preos |
| 781 |
The distribution PreOS plugins directory. |
| 782 |
/etc/cdist.cfg |
| 783 |
Global cdist configuration file, if exists. |
| 784 |
~/.cdist.cfg or $XDG_CONFIG_HOME/cdist/cdist.cfg |
| 785 |
Local cdist configuration file, if exists. |
| 786 |
|
| 787 |
NOTES |
| 788 |
----- |
| 789 |
cdist detects if host is specified by IPv6 address. If so then remote_copy |
| 790 |
command is executed with host address enclosed in square brackets |
| 791 |
(see :strong:`scp`\ (1)). |
| 792 |
|
| 793 |
EXAMPLES |
| 794 |
-------- |
| 795 |
|
| 796 |
.. code-block:: sh |
| 797 |
|
| 798 |
# Configure ikq05.ethz.ch with debug enabled |
| 799 |
% cdist config -vvv ikq05.ethz.ch |
| 800 |
|
| 801 |
# Configure hosts in parallel and use a different configuration directory |
| 802 |
% cdist config -c ~/p/cdist-nutzung \ |
| 803 |
-p ikq02.ethz.ch ikq03.ethz.ch ikq04.ethz.ch |
| 804 |
|
| 805 |
# Use custom remote exec / copy commands |
| 806 |
% cdist config --remote-exec /path/to/my/remote/exec \ |
| 807 |
--remote-copy /path/to/my/remote/copy \ |
| 808 |
-p ikq02.ethz.ch ikq03.ethz.ch ikq04.ethz.ch |
| 809 |
|
| 810 |
# Configure hosts read from file loadbalancers |
| 811 |
% cdist config -f loadbalancers |
| 812 |
|
| 813 |
# Configure hosts read from file web.hosts using 16 parallel jobs |
| 814 |
% cdist config -j 16 -f web.hosts |
| 815 |
|
| 816 |
# Display banner |
| 817 |
cdist banner |
| 818 |
|
| 819 |
# Show help |
| 820 |
% cdist --help |
| 821 |
|
| 822 |
# Show Version |
| 823 |
% cdist --version |
| 824 |
|
| 825 |
# Enter a shell that has access to emulated types |
| 826 |
% cdist shell |
| 827 |
% __git |
| 828 |
usage: __git --source SOURCE [--state STATE] [--branch BRANCH] |
| 829 |
[--group GROUP] [--owner OWNER] [--mode MODE] object_id |
| 830 |
|
| 831 |
# Install ikq05.ethz.ch with debug enabled |
| 832 |
% cdist install -vvv ikq05.ethz.ch |
| 833 |
|
| 834 |
# List inventory content |
| 835 |
% cdist inventory list -b |
| 836 |
|
| 837 |
# List inventory for specified host localhost |
| 838 |
% cdist inventory list -b localhost |
| 839 |
|
| 840 |
# List inventory for specified tag loadbalancer |
| 841 |
% cdist inventory list -b -t loadbalancer |
| 842 |
|
| 843 |
# Add hosts to inventory |
| 844 |
% cdist inventory add-host -b web1 web2 web3 |
| 845 |
|
| 846 |
# Delete hosts from file old-hosts from inventory |
| 847 |
% cdist inventory del-host -b -f old-hosts |
| 848 |
|
| 849 |
# Add tags to specified hosts |
| 850 |
% cdist inventory add-tag -b -t europe,croatia,web,static web1 web2 |
| 851 |
|
| 852 |
# Add tag to all hosts in inventory |
| 853 |
% cdist inventory add-tag -b -t vm |
| 854 |
|
| 855 |
# Delete all tags from specified host |
| 856 |
% cdist inventory del-tag -b -a localhost |
| 857 |
|
| 858 |
# Delete tags read from stdin from hosts specified by file hosts |
| 859 |
% cdist inventory del-tag -b -T - -f hosts |
| 860 |
|
| 861 |
# Configure hosts from inventory with any of specified tags |
| 862 |
% cdist config -b -t web dynamic |
| 863 |
|
| 864 |
# Configure hosts from inventory with all specified tags |
| 865 |
% cdist config -b -t -a web dynamic |
| 866 |
|
| 867 |
# Configure all hosts from inventory db |
| 868 |
$ cdist config -b -A |
| 869 |
|
| 870 |
# Create default debian PreOS in debug mode |
| 871 |
$ cdist preos debian /preos/preos-debian -vvvv -C \ |
| 872 |
-k ~/.ssh/id_rsa.pub -p /preos/pxe-debian |
| 873 |
|
| 874 |
# Create ubuntu PreOS |
| 875 |
$ cdist preos ubuntu /preos/preos-ubuntu -C \ |
| 876 |
-k ~/.ssh/id_rsa.pub -p /preos/pxe-ubuntu |
| 877 |
|
| 878 |
# Create ubuntu PreOS on drive /dev/sdb |
| 879 |
# and set root password to 'password'. |
| 880 |
$ cdist preos ubuntu /mnt -B -C \ |
| 881 |
-k ~/.ssh/id_rsa.pub -D /dev/sdb \ |
| 882 |
-P password |
| 883 |
|
| 884 |
|
| 885 |
ENVIRONMENT |
| 886 |
----------- |
| 887 |
TMPDIR, TEMP, TMP |
| 888 |
Setup the base directory for the temporary directory. |
| 889 |
See http://docs.python.org/py3k/library/tempfile.html for |
| 890 |
more information. This is rather useful, if the standard |
| 891 |
directory used does not allow executables. |
| 892 |
|
| 893 |
CDIST_PATH |
| 894 |
Colon delimited list of config directories. |
| 895 |
|
| 896 |
CDIST_LOCAL_SHELL |
| 897 |
Selects shell for local script execution, defaults to /bin/sh. |
| 898 |
|
| 899 |
CDIST_REMOTE_SHELL |
| 900 |
Selects shell for remote script execution, defaults to /bin/sh. |
| 901 |
|
| 902 |
CDIST_OVERRIDE |
| 903 |
Allow overwriting type parameters. |
| 904 |
|
| 905 |
CDIST_ORDER_DEPENDENCY |
| 906 |
Create dependencies based on the execution order. |
| 907 |
Note that in version 6.2.0 semantic of this processing mode is |
| 908 |
finally fixed and well defined. |
| 909 |
|
| 910 |
CDIST_REMOTE_EXEC |
| 911 |
Use this command for remote execution (should behave like ssh). |
| 912 |
|
| 913 |
CDIST_REMOTE_COPY |
| 914 |
Use this command for remote copy (should behave like scp). |
| 915 |
|
| 916 |
CDIST_INVENTORY_DIR |
| 917 |
Use this directory as inventory directory. |
| 918 |
|
| 919 |
CDIST_BETA |
| 920 |
Enable beta functionality. |
| 921 |
|
| 922 |
CDIST_CACHE_PATH_PATTERN |
| 923 |
Custom cache path pattern. |
| 924 |
|
| 925 |
CDIST_COLORED_OUTPUT |
| 926 |
Colorize cdist's output. cf. the :code:`--colors` option. |
| 927 |
|
| 928 |
CDIST_CONFIG_FILE |
| 929 |
Custom configuration file. |
| 930 |
|
| 931 |
|
| 932 |
EXIT STATUS |
| 933 |
----------- |
| 934 |
The following exit values shall be returned: |
| 935 |
|
| 936 |
0 Successful completion. |
| 937 |
|
| 938 |
1 One or more host configurations failed. |
| 939 |
|
| 940 |
|
| 941 |
AUTHORS |
| 942 |
------- |
| 943 |
Originally written by Nico Schottelius <[email protected]> |
| 944 |
and Steven Armstrong <[email protected]>. |
| 945 |
|
| 946 |
|
| 947 |
CAVEATS |
| 948 |
------- |
| 949 |
When operating in parallel, either by operating in parallel for each host |
| 950 |
(-p/--parallel) or by parallel jobs within a host (-j/--jobs), and depending |
| 951 |
on target SSH server and its configuration you may encounter connection drops. |
| 952 |
This is controlled with sshd :strong:`MaxStartups` configuration options. |
| 953 |
You may also encounter session open refusal. This happens with ssh multiplexing |
| 954 |
when you reach maximum number of open sessions permitted per network |
| 955 |
connection. In this case ssh will disable multiplexing. |
| 956 |
This limit is controlled with sshd :strong:`MaxSessions` configuration |
| 957 |
options. For more details refer to :strong:`sshd_config`\ (5). |
| 958 |
|
| 959 |
When requirements for the same object are defined in different manifests (see |
| 960 |
example below), for example, in init manifest and in some other type manifest |
| 961 |
and those requirements differ then dependency resolver cannot detect |
| 962 |
dependencies correctly. This happens because cdist cannot prepare all objects first |
| 963 |
and run all objects afterwards. Some object can depend on the result of type |
| 964 |
explorer(s) and explorers are executed during object run. cdist will detect |
| 965 |
such case and display a warning message. An example of such a case: |
| 966 |
|
| 967 |
.. code-block:: sh |
| 968 |
|
| 969 |
init manifest: |
| 970 |
__a a |
| 971 |
require="__e/e" __b b |
| 972 |
require="__f/f" __c c |
| 973 |
__e e |
| 974 |
__f f |
| 975 |
require="__c/c" __d d |
| 976 |
__g g |
| 977 |
__h h |
| 978 |
|
| 979 |
type __g manifest: |
| 980 |
require="__c/c __d/d" __a a |
| 981 |
|
| 982 |
Warning message: |
| 983 |
WARNING: cdisttesthost: Object __a/a already exists with requirements: |
| 984 |
/usr/home/darko/ungleich/cdist/cdist/test/config/fixtures/manifest/init-deps-resolver /tmp/tmp.cdist.test.ozagkg54/local/759547ff4356de6e3d9e08522b0d0807/data/conf/type/__g/manifest: set() |
| 985 |
/tmp/tmp.cdist.test.ozagkg54/local/759547ff4356de6e3d9e08522b0d0807/data/conf/type/__g/manifest: {'__c/c', '__d/d'} |
| 986 |
Dependency resolver could not handle dependencies as expected. |
| 987 |
|
| 988 |
COPYING |
| 989 |
------- |
| 990 |
Copyright \(C) 2011-2020 Nico Schottelius. Free use of this software is |
| 991 |
granted under the terms of the GNU General Public License v3 or later (GPLv3+). |