Debian Codegraph @

docs/src/man1/cdist.rst

raw
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+).