From 034a066063dabcf988ab683478d4731af358af24 Mon Sep 17 00:00:00 2001 From: Darko Poljak Date: Fri, 21 Jun 2019 14:22:50 +0200 Subject: [PATCH] Update beta manual --- .../manual/beta/_sources/cdist-type.rst.txt | 100 ++++++----- .../_sources/man7/cdist-type__acl.rst.txt | 65 ++++--- .../manual/beta/cdist-best-practice.html | 6 +- src/extra/manual/beta/cdist-bootstrap.html | 6 +- src/extra/manual/beta/cdist-cache.html | 6 +- .../manual/beta/cdist-configuration.html | 6 +- src/extra/manual/beta/cdist-explorer.html | 6 +- src/extra/manual/beta/cdist-features.html | 6 +- src/extra/manual/beta/cdist-hacker.html | 6 +- src/extra/manual/beta/cdist-install.html | 6 +- src/extra/manual/beta/cdist-integration.html | 6 +- src/extra/manual/beta/cdist-inventory.html | 6 +- src/extra/manual/beta/cdist-manifest.html | 6 +- src/extra/manual/beta/cdist-messaging.html | 6 +- src/extra/manual/beta/cdist-os.html | 6 +- .../manual/beta/cdist-parallelization.html | 6 +- src/extra/manual/beta/cdist-preos.html | 6 +- src/extra/manual/beta/cdist-quickstart.html | 6 +- src/extra/manual/beta/cdist-real-world.html | 6 +- src/extra/manual/beta/cdist-reference.html | 6 +- .../manual/beta/cdist-remote-exec-copy.html | 6 +- .../beta/cdist-saving-output-streams.html | 6 +- src/extra/manual/beta/cdist-stages.html | 6 +- src/extra/manual/beta/cdist-support.html | 6 +- src/extra/manual/beta/cdist-trigger.html | 6 +- .../manual/beta/cdist-troubleshooting.html | 6 +- src/extra/manual/beta/cdist-type.html | 160 +++++++++--------- src/extra/manual/beta/cdist-types.html | 6 +- src/extra/manual/beta/cdist-upgrade.html | 6 +- src/extra/manual/beta/cdist-why.html | 6 +- src/extra/manual/beta/genindex.html | 6 +- src/extra/manual/beta/index.html | 6 +- src/extra/manual/beta/man1/cdist-dump.html | 6 +- .../manual/beta/man1/cdist-new-type.html | 6 +- src/extra/manual/beta/man1/cdist.html | 6 +- .../manual/beta/man7/cdist-type__acl.html | 76 +++++---- .../man7/cdist-type__apt_default_release.html | 6 +- .../manual/beta/man7/cdist-type__apt_key.html | 6 +- .../beta/man7/cdist-type__apt_key_uri.html | 6 +- .../beta/man7/cdist-type__apt_mark.html | 6 +- .../man7/cdist-type__apt_norecommends.html | 6 +- .../manual/beta/man7/cdist-type__apt_ppa.html | 6 +- .../beta/man7/cdist-type__apt_source.html | 6 +- .../man7/cdist-type__apt_update_index.html | 6 +- .../manual/beta/man7/cdist-type__block.html | 6 +- .../man7/cdist-type__ccollect_source.html | 6 +- .../manual/beta/man7/cdist-type__cdist.html | 6 +- .../man7/cdist-type__cdist_preos_trigger.html | 6 +- .../beta/man7/cdist-type__cdistmarker.html | 6 +- .../beta/man7/cdist-type__check_messages.html | 6 +- .../beta/man7/cdist-type__chroot_mount.html | 6 +- .../beta/man7/cdist-type__chroot_umount.html | 6 +- .../beta/man7/cdist-type__clean_path.html | 6 +- .../beta/man7/cdist-type__config_file.html | 6 +- .../manual/beta/man7/cdist-type__consul.html | 6 +- .../beta/man7/cdist-type__consul_agent.html | 6 +- .../beta/man7/cdist-type__consul_check.html | 6 +- .../beta/man7/cdist-type__consul_reload.html | 6 +- .../beta/man7/cdist-type__consul_service.html | 6 +- .../man7/cdist-type__consul_template.html | 6 +- .../cdist-type__consul_template_template.html | 6 +- .../man7/cdist-type__consul_watch_checks.html | 6 +- .../man7/cdist-type__consul_watch_event.html | 6 +- .../man7/cdist-type__consul_watch_key.html | 6 +- .../cdist-type__consul_watch_keyprefix.html | 6 +- .../man7/cdist-type__consul_watch_nodes.html | 6 +- .../cdist-type__consul_watch_service.html | 6 +- .../cdist-type__consul_watch_services.html | 6 +- .../manual/beta/man7/cdist-type__cron.html | 6 +- .../beta/man7/cdist-type__daemontools.html | 6 +- .../man7/cdist-type__daemontools_service.html | 6 +- .../cdist-type__debconf_set_selections.html | 6 +- .../beta/man7/cdist-type__directory.html | 6 +- .../manual/beta/man7/cdist-type__docker.html | 6 +- .../beta/man7/cdist-type__docker_compose.html | 6 +- .../beta/man7/cdist-type__docker_config.html | 6 +- .../beta/man7/cdist-type__docker_secret.html | 6 +- .../beta/man7/cdist-type__docker_stack.html | 6 +- .../beta/man7/cdist-type__docker_swarm.html | 6 +- .../manual/beta/man7/cdist-type__dog_vdi.html | 6 +- .../beta/man7/cdist-type__dot_file.html | 6 +- .../manual/beta/man7/cdist-type__file.html | 6 +- .../beta/man7/cdist-type__filesystem.html | 6 +- .../beta/man7/cdist-type__firewalld_rule.html | 6 +- .../man7/cdist-type__firewalld_start.html | 6 +- .../manual/beta/man7/cdist-type__git.html | 6 +- .../manual/beta/man7/cdist-type__go_get.html | 6 +- .../man7/cdist-type__golang_from_vendor.html | 6 +- .../man7/cdist-type__grafana_dashboard.html | 6 +- .../manual/beta/man7/cdist-type__group.html | 6 +- .../beta/man7/cdist-type__hostname.html | 6 +- .../manual/beta/man7/cdist-type__hosts.html | 6 +- .../cdist-type__install_bootloader_grub.html | 6 +- .../cdist-type__install_chroot_mount.html | 6 +- .../cdist-type__install_chroot_umount.html | 6 +- .../beta/man7/cdist-type__install_config.html | 6 +- .../beta/man7/cdist-type__install_coreos.html | 6 +- .../man7/cdist-type__install_directory.html | 6 +- .../beta/man7/cdist-type__install_file.html | 6 +- .../beta/man7/cdist-type__install_fstab.html | 6 +- .../cdist-type__install_generate_fstab.html | 6 +- .../beta/man7/cdist-type__install_mkfs.html | 6 +- .../beta/man7/cdist-type__install_mount.html | 6 +- .../cdist-type__install_partition_msdos.html | 6 +- ...t-type__install_partition_msdos_apply.html | 6 +- .../beta/man7/cdist-type__install_reboot.html | 6 +- .../man7/cdist-type__install_reset_disk.html | 6 +- .../beta/man7/cdist-type__install_stage.html | 6 +- .../beta/man7/cdist-type__install_umount.html | 6 +- .../beta/man7/cdist-type__iptables_apply.html | 6 +- .../beta/man7/cdist-type__iptables_rule.html | 6 +- .../manual/beta/man7/cdist-type__issue.html | 6 +- .../manual/beta/man7/cdist-type__jail.html | 6 +- .../beta/man7/cdist-type__jail_freebsd10.html | 6 +- .../beta/man7/cdist-type__jail_freebsd9.html | 6 +- .../beta/man7/cdist-type__key_value.html | 6 +- .../beta/man7/cdist-type__keyboard.html | 6 +- .../man7/cdist-type__letsencrypt_cert.html | 6 +- .../manual/beta/man7/cdist-type__line.html | 6 +- .../manual/beta/man7/cdist-type__link.html | 6 +- .../manual/beta/man7/cdist-type__locale.html | 6 +- .../beta/man7/cdist-type__locale_system.html | 6 +- .../manual/beta/man7/cdist-type__motd.html | 6 +- .../manual/beta/man7/cdist-type__mount.html | 6 +- .../beta/man7/cdist-type__mysql_database.html | 6 +- .../manual/beta/man7/cdist-type__package.html | 6 +- .../beta/man7/cdist-type__package_apk.html | 6 +- .../beta/man7/cdist-type__package_apt.html | 6 +- .../beta/man7/cdist-type__package_dpkg.html | 6 +- .../beta/man7/cdist-type__package_emerge.html | 6 +- ...ist-type__package_emerge_dependencies.html | 6 +- .../man7/cdist-type__package_luarocks.html | 6 +- .../beta/man7/cdist-type__package_opkg.html | 6 +- .../beta/man7/cdist-type__package_pacman.html | 6 +- .../beta/man7/cdist-type__package_pip.html | 6 +- .../man7/cdist-type__package_pkg_freebsd.html | 6 +- .../man7/cdist-type__package_pkg_openbsd.html | 6 +- .../cdist-type__package_pkgng_freebsd.html | 6 +- .../man7/cdist-type__package_rubygem.html | 6 +- .../cdist-type__package_update_index.html | 6 +- .../man7/cdist-type__package_upgrade_all.html | 6 +- .../beta/man7/cdist-type__package_yum.html | 6 +- .../beta/man7/cdist-type__package_zypper.html | 6 +- .../beta/man7/cdist-type__pacman_conf.html | 6 +- .../cdist-type__pacman_conf_integrate.html | 6 +- .../beta/man7/cdist-type__pf_apply.html | 6 +- .../beta/man7/cdist-type__pf_ruleset.html | 6 +- .../manual/beta/man7/cdist-type__ping.html | 6 +- .../manual/beta/man7/cdist-type__postfix.html | 6 +- .../beta/man7/cdist-type__postfix_master.html | 6 +- .../man7/cdist-type__postfix_postconf.html | 6 +- .../man7/cdist-type__postfix_postmap.html | 6 +- .../beta/man7/cdist-type__postfix_reload.html | 6 +- .../man7/cdist-type__postgres_database.html | 6 +- .../man7/cdist-type__postgres_extension.html | 6 +- .../beta/man7/cdist-type__postgres_role.html | 6 +- .../manual/beta/man7/cdist-type__process.html | 6 +- .../cdist-type__prometheus_alertmanager.html | 6 +- .../man7/cdist-type__prometheus_exporter.html | 6 +- .../man7/cdist-type__prometheus_server.html | 6 +- .../manual/beta/man7/cdist-type__pyvenv.html | 6 +- .../beta/man7/cdist-type__qemu_img.html | 6 +- .../manual/beta/man7/cdist-type__rbenv.html | 6 +- .../manual/beta/man7/cdist-type__rsync.html | 6 +- .../manual/beta/man7/cdist-type__rvm.html | 6 +- .../manual/beta/man7/cdist-type__rvm_gem.html | 6 +- .../beta/man7/cdist-type__rvm_gemset.html | 6 +- .../beta/man7/cdist-type__rvm_ruby.html | 6 +- .../man7/cdist-type__ssh_authorized_key.html | 6 +- .../man7/cdist-type__ssh_authorized_keys.html | 6 +- .../beta/man7/cdist-type__ssh_dot_ssh.html | 6 +- .../beta/man7/cdist-type__staged_file.html | 6 +- .../beta/man7/cdist-type__start_on_boot.html | 6 +- .../manual/beta/man7/cdist-type__sysctl.html | 6 +- .../beta/man7/cdist-type__systemd_unit.html | 6 +- .../beta/man7/cdist-type__timezone.html | 6 +- .../manual/beta/man7/cdist-type__ufw.html | 6 +- .../beta/man7/cdist-type__ufw_rule.html | 6 +- .../man7/cdist-type__update_alternatives.html | 6 +- .../manual/beta/man7/cdist-type__user.html | 6 +- .../beta/man7/cdist-type__user_groups.html | 6 +- .../beta/man7/cdist-type__yum_repo.html | 6 +- .../beta/man7/cdist-type__zypper_repo.html | 6 +- .../beta/man7/cdist-type__zypper_service.html | 6 +- src/extra/manual/beta/objects.inv | Bin 2658 -> 2658 bytes src/extra/manual/beta/search.html | 6 +- src/extra/manual/beta/searchindex.js | 2 +- 187 files changed, 758 insertions(+), 731 deletions(-) diff --git a/src/extra/manual/beta/_sources/cdist-type.rst.txt b/src/extra/manual/beta/_sources/cdist-type.rst.txt index 12a203b7..3a4a0b13 100644 --- a/src/extra/manual/beta/_sources/cdist-type.rst.txt +++ b/src/extra/manual/beta/_sources/cdist-type.rst.txt @@ -74,7 +74,7 @@ prevents to be run in more than one instance. Deprecated types ----------------- If a type is flagged with 'deprecated' marker then it is considered deprecated. -Upon it's usage cdist writes warning line. If 'deprecated' marker has content +When it is used cdist writes warning line. If 'deprecated' marker has content then this content is printed as a deprecation messages, e.g.: .. code-block:: sh @@ -186,6 +186,31 @@ Example: (e.g. in cdist/conf/type/__nginx_vhost/manifest) fi +Deprecated parameters +--------------------- +To deprecate type parameters one can declare a file for each deprecated +parameter under **parameter/deprecated** directory. + +When such parameter is used cdist writes warning line with deprecation message. +If such file has content then this content is printed as deprecation message. +If there is no content then generic parameter deprecation message is printed. + +Example: + +.. code-block:: sh + + $ ls parameter/deprecated/ + eggs spam + $ cat parameter/deprecated/eggs + eggs parameter is deprecated, please use multiple egg parameter. + $ cat parameter/deprecated/spam + $ echo '__foo foo --foo foo --eggs eggs' | ./bin/cdist config -i - 185.203.112.26 + WARNING: 185.203.112.26: eggs parameter of type __foo is deprecated: eggs parameter is deprecated, please use multiple egg parameter. + $ echo '__foo foo --foo foo --eggs eggs --spam spam' | ./bin/cdist config -i - 185.203.112.26 + WARNING: 185.203.112.26: spam parameter of type __foo is deprecated. + WARNING: 185.203.112.26: eggs parameter of type __foo is deprecated: eggs parameter is deprecated, please use multiple egg parameter. + + Input from stdin ---------------- Every type can access what has been written on stdin when it has been called. @@ -514,62 +539,43 @@ Core python types replace manifest and gencode scripts. Parameters, singleton, nonparallel are still defined as for common types. Explorer code is also written in shell, since this is the code that is directly executed at target host. -When writing python type you can extend **cdist.core.PythonType** class. +When writing python type you can extend **cdist.core.pytypes.PythonType** class. You need to implement the following methods: -* **type_manifest**: implementation should yield **cdist.core.ManifestEntry** - instances, or **yield from ()** if type does not use other types +* **type_manifest**: implementation should yield **cdist.core.pytypes.** + attribute function call result, or **yield from ()** if type does not use other types * **type_gencode**: implementation should return a string consisting of lines of shell code that will be executed at target host. -**cdist.core.ManifestEntry** is a python type way for invoking another cdist type. +**cdist.core.pytypes.** attributes correspond to detected python types. +**Note** that double underscore ('__') at the beginning of type name is removed. + Example: .. code-block:: sh - ... - class DummyConfig(PythonType): - def type_manifest(self): - # Invoking pyhton file type with provided stdin source with - # specified content. - filepy = ManifestEntry(name='__file_py', stdin='dummy=py\n', - parameters={ - '/root/dummypy.conf': None, - '--mode': '0640', - '--owner': 'root', - '--group': 'root', - '--source': '-', - }) - yield filepy + import os + import sys + from cdist.core.pytypes import * - # Invoking pyhton file type with specified file as source. - self_path = os.path.dirname(os.path.realpath(__file__)) - conf_path = os.path.join(self_path, 'files', 'dummypy.conf') - filepy = ManifestEntry(name='__file_py', - parameters={ - '/root/dummypy2.conf': None, - '--mode': '0640', - '--owner': 'root', - '--group': 'root', - '--source': conf_path, - }) - yield filepy - # Invoking standard shell file type with stdin source feeded - # from file. - self_path = os.path.dirname(os.path.realpath(__file__)) - conf_path = os.path.join(self_path, 'files', 'dummysh.conf') - with open(conf_path, 'r') as f: - filepy = ManifestEntry(name='__file', stdin=f, - parameters={ - '/root/dummysh.conf': None, - '--mode': '0600', - '--owner': 'root', - '--group': 'root', - '--source': '-', - }) - yield filepy - ... + class DummyConfig(PythonType): + def type_manifest(self): + print('dummy manifest stdout') + print('dummy manifest stderr\n', file=sys.stderr) + yield file_py('/root/dummy1.conf', + mode='0640', + owner='root', + group='root', + source='-').feed_stdin('dummy=1\n') + + self_path = os.path.dirname(os.path.realpath(__file__)) + conf_path = os.path.join(self_path, 'files', 'dummy.conf') + yield file_py('/root/dummy2.conf', + mode='0640', + owner='root', + group='root', + source=conf_path) **cdist.core.PythonType** class provides the following methods: @@ -593,7 +599,7 @@ Furthermore, under **docs/dev/python-types** there are sample cdist conf directo init manifests and scripts for running and measuring duration of samples. There, under **conf/type/__dummy_config** you can find another example of python type, which (unlike **__file_py** type) also uses new manifest implementation -that yields **ManifestEntry** instances. +that yields **cdist.core.pytypes.** attribute function call results. **NOTE** that python types implementation is under the beta, not directly controled by the **-b/--beta** option. It is controled by the explicit usage of python types in diff --git a/src/extra/manual/beta/_sources/man7/cdist-type__acl.rst.txt b/src/extra/manual/beta/_sources/man7/cdist-type__acl.rst.txt index d066aae5..85e946ce 100644 --- a/src/extra/manual/beta/_sources/man7/cdist-type__acl.rst.txt +++ b/src/extra/manual/beta/_sources/man7/cdist-type__acl.rst.txt @@ -8,42 +8,36 @@ cdist-type__acl - Set ACL entries DESCRIPTION ----------- -ACL must be defined as 3-symbol combination, using ``r``, ``w``, ``x`` and ``-``. - Fully supported and tested on Linux (ext4 filesystem), partial support for FreeBSD. See ``setfacl`` and ``acl`` manpages for more details. -OPTIONAL MULTIPLE PARAMETERS +REQUIRED MULTIPLE PARAMETERS ---------------------------- -user - Add user ACL entry. - -group - Add group ACL entry. - - -OPTIONAL PARAMETERS -------------------- -mask - Add mask ACL entry. - -other - Add other ACL entry. +acl + Set ACL entry following ``getfacl`` output syntax. BOOLEAN PARAMETERS ------------------ +default + Set all ACL entries as default too. + Only directories can have default ACLs. + Setting default ACL in FreeBSD is currently not supported. + recursive Make ``setfacl`` recursive (Linux only), but not ``getfacl`` in explorer. -default - Add default ACL entries (FreeBSD not supported). - remove - Remove undefined ACL entries (Solaris not supported). - ACL entries for ``mask`` and ``other`` can't be removed. + Remove undefined ACL entries. + ``mask`` and ``other`` entries can't be removed, but only changed. + + +DEPRECATED PARAMETERS +--------------------- +Parameters ``user``, ``group``, ``mask`` and ``other`` are deprecated and they +will be removed in future versions. Please use ``acl`` parameter instead. EXAMPLES @@ -52,15 +46,30 @@ EXAMPLES .. code-block:: sh __acl /srv/project \ + --default \ --recursive \ + --remove \ + --acl user:alice:rwx \ + --acl user:bob:r-x \ + --acl group:project-group:rwx \ + --acl group:some-other-group:r-x \ + --acl mask::r-x \ + --acl other::r-x + + # give Alice read-only access to subdir, + # but don't allow her to see parent content. + + __acl /srv/project2 \ + --remove \ + --acl default:group:secret-project:rwx \ + --acl group:secret-project:rwx \ + --acl user:alice:--x + + __acl /srv/project2/subdir \ --default \ --remove \ - --user alice:rwx \ - --user bob:r-x \ - --group project-group:rwx \ - --group some-other-group:r-x \ - --mask r-x \ - --other r-x + --acl group:secret-project:rwx \ + --acl user:alice:r-x AUTHORS diff --git a/src/extra/manual/beta/cdist-best-practice.html b/src/extra/manual/beta/cdist-best-practice.html index aae026f7..c08cef3e 100644 --- a/src/extra/manual/beta/cdist-best-practice.html +++ b/src/extra/manual/beta/cdist-best-practice.html @@ -8,7 +8,7 @@ - 25. Best practice — cdist 5.1.1 documentation + 25. Best practice — cdist 5.1.2 documentation @@ -23,7 +23,7 @@