diff options
Diffstat (limited to 'lib/ansible/plugins/doc_fragments')
19 files changed, 1201 insertions, 0 deletions
diff --git a/lib/ansible/plugins/doc_fragments/__init__.py b/lib/ansible/plugins/doc_fragments/__init__.py new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/lib/ansible/plugins/doc_fragments/__init__.py diff --git a/lib/ansible/plugins/doc_fragments/action_common_attributes.py b/lib/ansible/plugins/doc_fragments/action_common_attributes.py new file mode 100644 index 0000000..c135df5 --- /dev/null +++ b/lib/ansible/plugins/doc_fragments/action_common_attributes.py @@ -0,0 +1,71 @@ +# -*- coding: utf-8 -*- +# Copyright: Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + + +class ModuleDocFragment(object): + + # Standard documentation fragment + DOCUMENTATION = r''' +attributes: + check_mode: + description: Can run in check_mode and return changed status prediction without modifying target + diff_mode: + description: Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode + platform: + description: Target OS/families that can be operated against + support: N/A +''' + + ACTIONGROUPS = r''' +attributes: + action_group: + description: Action is part of action_group(s), for convenient setting of module_defaults. + support: N/A + membership: [] +''' + + CONN = r''' +attributes: + become: + description: Is usable alongside become keywords + connection: + description: Uses the target's configured connection information to execute code on it + delegation: + description: Can be used in conjunction with delegate_to and related keywords +''' + + FACTS = r''' +attributes: + facts: + description: Action returns an C(ansible_facts) dictionary that will update existing host facts +''' + + FILES = r''' +attributes: + safe_file_operations: + description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption + vault: + description: Can automatically decrypt Ansible vaulted files +''' + + FLOW = r''' +attributes: + action: + description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller + async: + description: Supports being used with the C(async) keyword + bypass_host_loop: + description: + - Forces a 'global' task that does not execute per host, this bypasses per host templating and serial, + throttle and other loop considerations + - Conditionals will work as if C(run_once) is being used, variables used will be from the first available host + - This action will not work normally outside of lockstep strategies +''' + RAW = r''' +attributes: + raw: + description: Indicates if an action takes a 'raw' or 'free form' string as an option and has it's own special parsing of it +''' diff --git a/lib/ansible/plugins/doc_fragments/action_core.py b/lib/ansible/plugins/doc_fragments/action_core.py new file mode 100644 index 0000000..931ca14 --- /dev/null +++ b/lib/ansible/plugins/doc_fragments/action_core.py @@ -0,0 +1,80 @@ +# -*- coding: utf-8 -*- +# Copyright: (c) , Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + + +# WARNING: this is mostly here as a convinence for documenting core behaviours, no plugin outside of ansible-core should use this file +class ModuleDocFragment(object): + + # requires action_common + DOCUMENTATION = r''' +attributes: + async: + support: none + become: + support: none + bypass_task_loop: + description: These tasks ignore the C(loop) and C(with_) keywords + core: + description: This is a 'core engine' feature and is not implemented like most task actions, so it is not overridable in any way via the plugin system. + support: full + connection: + support: none + ignore_conditional: + support: none + description: The action is not subject to conditional execution so it will ignore the C(when:) keyword + platform: + support: full + platforms: all + until: + description: Denotes if this action objeys until/retry/poll keywords + support: full + tags: + description: Allows for the 'tags' keyword to control the selection of this action for execution + support: full +''' + + # also requires core above + IMPORT = r''' +attributes: + action: + details: While this action executes locally on the controller it is not governed by an action plugin + support: none + bypass_host_loop: + details: While the import can be host specific and runs per host it is not dealing with all available host variables, + use an include instead for those cases + support: partial + bypass_task_loop: + details: The task itself is not looped, but the loop is applied to each imported task + support: partial + delegation: + details: Since there are no connection nor facts, there is no sense in delegating imports + support: none + ignore_conditional: + details: While the action itself will ignore the conditional, it will be inherited by the imported tasks themselves + support: partial + tags: + details: Tags are not interpreted for this action, they are applied to the imported tasks + support: none + until: + support: none +''' + # also requires core above + INCLUDE = r''' +attributes: + action: + details: While this action executes locally on the controller it is not governed by an action plugin + support: none + bypass_host_loop: + support: none + bypass_task_loop: + support: none + delegation: + details: Since there are no connection nor facts, there is no sense in delegating includes + support: none + tags: + details: Tags are interpreted by this action but are not automatically inherited by the include tasks, see C(apply) + support: partial +''' diff --git a/lib/ansible/plugins/doc_fragments/backup.py b/lib/ansible/plugins/doc_fragments/backup.py new file mode 100644 index 0000000..d2e76dc --- /dev/null +++ b/lib/ansible/plugins/doc_fragments/backup.py @@ -0,0 +1,20 @@ +# -*- coding: utf-8 -*- + +# Copyright: (c) 2015, Ansible, Inc +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + + +class ModuleDocFragment(object): + + # Standard documentation fragment + DOCUMENTATION = r''' +options: + backup: + description: + - Create a backup file including the timestamp information so you can get + the original file back if you somehow clobbered it incorrectly. + type: bool + default: no +''' diff --git a/lib/ansible/plugins/doc_fragments/connection_pipelining.py b/lib/ansible/plugins/doc_fragments/connection_pipelining.py new file mode 100644 index 0000000..fa18265 --- /dev/null +++ b/lib/ansible/plugins/doc_fragments/connection_pipelining.py @@ -0,0 +1,31 @@ +# Copyright (c) 2021 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + + +class ModuleDocFragment(object): + + # common shelldocumentation fragment + DOCUMENTATION = """ +options: + pipelining: + default: false + description: + - Pipelining reduces the number of connection operations required to execute a module on the remote server, + by executing many Ansible modules without actual file transfers. + - This can result in a very significant performance improvement when enabled. + - However this can conflict with privilege escalation (become). + For example, when using sudo operations you must first disable 'requiretty' in the sudoers file for the target hosts, + which is why this feature is disabled by default. + env: + - name: ANSIBLE_PIPELINING + ini: + - section: defaults + key: pipelining + - section: connection + key: pipelining + type: boolean + vars: + - name: ansible_pipelining +""" diff --git a/lib/ansible/plugins/doc_fragments/constructed.py b/lib/ansible/plugins/doc_fragments/constructed.py new file mode 100644 index 0000000..7810acb --- /dev/null +++ b/lib/ansible/plugins/doc_fragments/constructed.py @@ -0,0 +1,83 @@ +# -*- coding: utf-8 -*- + +# Copyright: (c) 2017, Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + + +class ModuleDocFragment(object): + + DOCUMENTATION = r''' +options: + strict: + description: + - If C(yes) make invalid entries a fatal error, otherwise skip and continue. + - Since it is possible to use facts in the expressions they might not always be available + and we ignore those errors by default. + type: bool + default: no + compose: + description: Create vars from jinja2 expressions. + type: dict + default: {} + groups: + description: Add hosts to group based on Jinja2 conditionals. + type: dict + default: {} + keyed_groups: + description: Add hosts to group based on the values of a variable. + type: list + default: [] + elements: dict + suboptions: + parent_group: + type: str + description: parent group for keyed group + prefix: + type: str + description: A keyed group name will start with this prefix + default: '' + separator: + type: str + description: separator used to build the keyed group name + default: "_" + key: + type: str + description: + - The key from input dictionary used to generate groups + default_value: + description: + - The default value when the host variable's value is an empty string. + - This option is mutually exclusive with C(trailing_separator). + type: str + version_added: '2.12' + trailing_separator: + description: + - Set this option to I(False) to omit the C(separator) after the host variable when the value is an empty string. + - This option is mutually exclusive with C(default_value). + type: bool + default: True + version_added: '2.12' + use_extra_vars: + version_added: '2.11' + description: Merge extra vars into the available variables for composition (highest precedence). + type: bool + default: False + ini: + - section: inventory_plugins + key: use_extra_vars + env: + - name: ANSIBLE_INVENTORY_USE_EXTRA_VARS + leading_separator: + description: + - Use in conjunction with keyed_groups. + - By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore. + - This is because the default prefix is "" and the default separator is "_". + - Set this option to False to omit the leading underscore (or other separator) if no prefix is given. + - If the group name is derived from a mapping the separator is still used to concatenate the items. + - To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead. + type: boolean + default: True + version_added: '2.11' +''' diff --git a/lib/ansible/plugins/doc_fragments/decrypt.py b/lib/ansible/plugins/doc_fragments/decrypt.py new file mode 100644 index 0000000..ea7cf59 --- /dev/null +++ b/lib/ansible/plugins/doc_fragments/decrypt.py @@ -0,0 +1,20 @@ +# -*- coding: utf-8 -*- + +# Copyright: (c) 2017, Brian Coca <bcoca@redhat.com> +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + + +class ModuleDocFragment(object): + + # Standard files documentation fragment + DOCUMENTATION = r''' +options: + decrypt: + description: + - This option controls the autodecryption of source files using vault. + type: bool + default: yes + version_added: '2.4' +''' diff --git a/lib/ansible/plugins/doc_fragments/default_callback.py b/lib/ansible/plugins/doc_fragments/default_callback.py new file mode 100644 index 0000000..5798334 --- /dev/null +++ b/lib/ansible/plugins/doc_fragments/default_callback.py @@ -0,0 +1,93 @@ +# -*- coding: utf-8 -*- + +# Copyright: (c) 2017, Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + + +class ModuleDocFragment(object): + + DOCUMENTATION = r''' + options: + display_skipped_hosts: + name: Show skipped hosts + description: "Toggle to control displaying skipped task/host results in a task" + type: bool + default: yes + env: + - name: ANSIBLE_DISPLAY_SKIPPED_HOSTS + ini: + - key: display_skipped_hosts + section: defaults + display_ok_hosts: + name: Show 'ok' hosts + description: "Toggle to control displaying 'ok' task/host results in a task" + type: bool + default: yes + env: + - name: ANSIBLE_DISPLAY_OK_HOSTS + ini: + - key: display_ok_hosts + section: defaults + version_added: '2.7' + display_failed_stderr: + name: Use STDERR for failed and unreachable tasks + description: "Toggle to control whether failed and unreachable tasks are displayed to STDERR (vs. STDOUT)" + type: bool + default: no + env: + - name: ANSIBLE_DISPLAY_FAILED_STDERR + ini: + - key: display_failed_stderr + section: defaults + version_added: '2.7' + show_custom_stats: + name: Show custom stats + description: 'This adds the custom stats set via the set_stats plugin to the play recap' + type: bool + default: no + env: + - name: ANSIBLE_SHOW_CUSTOM_STATS + ini: + - key: show_custom_stats + section: defaults + show_per_host_start: + name: Show per host task start + description: 'This adds output that shows when a task is started to execute for each host' + type: bool + default: no + env: + - name: ANSIBLE_SHOW_PER_HOST_START + ini: + - key: show_per_host_start + section: defaults + version_added: '2.9' + check_mode_markers: + name: Show markers when running in check mode + description: + - Toggle to control displaying markers when running in check mode. + - "The markers are C(DRY RUN) at the beginning and ending of playbook execution (when calling C(ansible-playbook --check)) + and C(CHECK MODE) as a suffix at every play and task that is run in check mode." + type: bool + default: no + version_added: '2.9' + env: + - name: ANSIBLE_CHECK_MODE_MARKERS + ini: + - key: check_mode_markers + section: defaults + show_task_path_on_failure: + name: Show file path on failed tasks + description: + When a task fails, display the path to the file containing the failed task and the line number. + This information is displayed automatically for every task when running with C(-vv) or greater verbosity. + type: bool + default: no + env: + - name: ANSIBLE_SHOW_TASK_PATH_ON_FAILURE + ini: + - key: show_task_path_on_failure + section: defaults + version_added: '2.11' +''' diff --git a/lib/ansible/plugins/doc_fragments/files.py b/lib/ansible/plugins/doc_fragments/files.py new file mode 100644 index 0000000..b87fd11 --- /dev/null +++ b/lib/ansible/plugins/doc_fragments/files.py @@ -0,0 +1,91 @@ +# -*- coding: utf-8 -*- + +# Copyright: (c) 2014, Matt Martz <matt@sivel.net> +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + + +class ModuleDocFragment(object): + + # Standard files documentation fragment + + # Note: mode is overridden by the copy and template modules so if you change the description + # here, you should also change it there. + DOCUMENTATION = r''' +options: + mode: + description: + - The permissions the resulting filesystem object should have. + - For those used to I(/usr/bin/chmod) remember that modes are actually octal numbers. + You must either add a leading zero so that Ansible's YAML parser knows it is an octal number + (like C(0644) or C(01777)) or quote it (like C('644') or C('1777')) so Ansible receives + a string and can do its own conversion from string into number. + - Giving Ansible a number without following one of these rules will end up with a decimal + number which will have unexpected results. + - As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or + C(u=rw,g=r,o=r)). + - If C(mode) is not specified and the destination filesystem object B(does not) exist, the default C(umask) on the system will be used + when setting the mode for the newly created filesystem object. + - If C(mode) is not specified and the destination filesystem object B(does) exist, the mode of the existing filesystem object will be used. + - Specifying C(mode) is the best way to ensure filesystem objects are created with the correct permissions. + See CVE-2020-1736 for further details. + type: raw + owner: + description: + - Name of the user that should own the filesystem object, as would be fed to I(chown). + - When left unspecified, it uses the current user unless you are root, in which + case it can preserve the previous ownership. + - Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. + + type: str + group: + description: + - Name of the group that should own the filesystem object, as would be fed to I(chown). + - When left unspecified, it uses the current group of the current user unless you are root, + in which case it can preserve the previous ownership. + type: str + seuser: + description: + - The user part of the SELinux filesystem object context. + - By default it uses the C(system) policy, where applicable. + - When set to C(_default), it will use the C(user) portion of the policy if available. + type: str + serole: + description: + - The role part of the SELinux filesystem object context. + - When set to C(_default), it will use the C(role) portion of the policy if available. + type: str + setype: + description: + - The type part of the SELinux filesystem object context. + - When set to C(_default), it will use the C(type) portion of the policy if available. + type: str + selevel: + description: + - The level part of the SELinux filesystem object context. + - This is the MLS/MCS attribute, sometimes known as the C(range). + - When set to C(_default), it will use the C(level) portion of the policy if available. + type: str + unsafe_writes: + description: + - Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target filesystem object. + - By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target filesystem objects, + but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted filesystem objects, + which cannot be updated atomically from inside the container and can only be written in an unsafe manner. + - This option allows Ansible to fall back to unsafe methods of updating filesystem objects when atomic operations fail + (however, it doesn't force Ansible to perform unsafe writes). + - IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption. + type: bool + default: no + version_added: '2.2' + attributes: + description: + - The attributes the resulting filesystem object should have. + - To get supported flags look at the man page for I(chattr) on the target system. + - This string should contain the attributes in the same order as the one displayed by I(lsattr). + - The C(=) operator is assumed as default, otherwise C(+) or C(-) operators need to be included in the string. + type: str + aliases: [ attr ] + version_added: '2.3' +''' diff --git a/lib/ansible/plugins/doc_fragments/inventory_cache.py b/lib/ansible/plugins/doc_fragments/inventory_cache.py new file mode 100644 index 0000000..9326c3f --- /dev/null +++ b/lib/ansible/plugins/doc_fragments/inventory_cache.py @@ -0,0 +1,80 @@ +# -*- coding: utf-8 -*- + +# Copyright: (c) 2017, Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + + +class ModuleDocFragment(object): + + # inventory cache + DOCUMENTATION = r''' +options: + cache: + description: + - Toggle to enable/disable the caching of the inventory's source data, requires a cache plugin setup to work. + type: bool + default: no + env: + - name: ANSIBLE_INVENTORY_CACHE + ini: + - section: inventory + key: cache + cache_plugin: + description: + - Cache plugin to use for the inventory's source data. + type: str + default: memory + env: + - name: ANSIBLE_CACHE_PLUGIN + - name: ANSIBLE_INVENTORY_CACHE_PLUGIN + ini: + - section: defaults + key: fact_caching + - section: inventory + key: cache_plugin + cache_timeout: + description: + - Cache duration in seconds + default: 3600 + type: int + env: + - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT + - name: ANSIBLE_INVENTORY_CACHE_TIMEOUT + ini: + - section: defaults + key: fact_caching_timeout + - section: inventory + key: cache_timeout + cache_connection: + description: + - Cache connection data or path, read cache plugin documentation for specifics. + type: str + env: + - name: ANSIBLE_CACHE_PLUGIN_CONNECTION + - name: ANSIBLE_INVENTORY_CACHE_CONNECTION + ini: + - section: defaults + key: fact_caching_connection + - section: inventory + key: cache_connection + cache_prefix: + description: + - Prefix to use for cache plugin files/tables + default: ansible_inventory_ + env: + - name: ANSIBLE_CACHE_PLUGIN_PREFIX + - name: ANSIBLE_INVENTORY_CACHE_PLUGIN_PREFIX + ini: + - section: default + key: fact_caching_prefix + deprecated: + alternatives: Use the 'defaults' section instead + why: Fixes typing error in INI section name + version: '2.16' + - section: defaults + key: fact_caching_prefix + - section: inventory + key: cache_prefix +''' diff --git a/lib/ansible/plugins/doc_fragments/result_format_callback.py b/lib/ansible/plugins/doc_fragments/result_format_callback.py new file mode 100644 index 0000000..1b71173 --- /dev/null +++ b/lib/ansible/plugins/doc_fragments/result_format_callback.py @@ -0,0 +1,50 @@ +# -*- coding: utf-8 -*- + +# Copyright: (c) 2017, Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + + +class ModuleDocFragment(object): + + DOCUMENTATION = r''' + options: + result_format: + name: Format of the task result + description: + - Define the task result format used in the callback output. + - These formats do not cause the callback to emit valid JSON or YAML formats. + - The output contains these formats interspersed with other non-machine parsable data. + type: str + default: json + env: + - name: ANSIBLE_CALLBACK_RESULT_FORMAT + ini: + - key: callback_result_format + section: defaults + choices: + - json + - yaml + version_added: '2.13' + pretty_results: + name: Configure output for readability + description: + - Configure the result format to be more readable + - When the result format is set to C(yaml) this option defaults to C(True), and defaults + to C(False) when configured to C(json). + - Setting this option to C(True) will force C(json) and C(yaml) results to always be pretty + printed regardless of verbosity. + - When set to C(True) and used with the C(yaml) result format, this option will + modify module responses in an attempt to produce a more human friendly output at the expense + of correctness, and should not be relied upon to aid in writing variable manipulations + or conditionals. For correctness, set this option to C(False) or set the result format to C(json). + type: bool + default: null + env: + - name: ANSIBLE_CALLBACK_FORMAT_PRETTY + ini: + - key: callback_format_pretty + section: defaults + version_added: '2.13' +''' diff --git a/lib/ansible/plugins/doc_fragments/return_common.py b/lib/ansible/plugins/doc_fragments/return_common.py new file mode 100644 index 0000000..6f54288 --- /dev/null +++ b/lib/ansible/plugins/doc_fragments/return_common.py @@ -0,0 +1,42 @@ +# -*- coding: utf-8 -*- + +# Copyright: (c) 2016, Ansible, Inc +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + + +class ModuleDocFragment(object): + # Standard documentation fragment + RETURN = r''' +changed: + description: Whether the module affected changes on the target. + returned: always + type: bool + sample: false +failed: + description: Whether the module failed to execute. + returned: always + type: bool + sample: true +msg: + description: Human-readable message. + returned: as needed + type: str + sample: all ok +skipped: + description: Whether the module was skipped. + returned: always + type: bool + sample: false +results: + description: List of module results, + returned: when using a loop. + type: list + sample: [{changed: True, msg: 'first item changed'}, {changed: False, msg: 'second item ok'}] +exception: + description: Optional information from a handled error. + returned: on some errors + type: str + sample: Unknown error +''' diff --git a/lib/ansible/plugins/doc_fragments/shell_common.py b/lib/ansible/plugins/doc_fragments/shell_common.py new file mode 100644 index 0000000..fe1ae4e --- /dev/null +++ b/lib/ansible/plugins/doc_fragments/shell_common.py @@ -0,0 +1,98 @@ +# Copyright (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + + +class ModuleDocFragment(object): + + # common shelldocumentation fragment + DOCUMENTATION = """ +options: + remote_tmp: + description: + - Temporary directory to use on targets when executing tasks. + default: '~/.ansible/tmp' + env: [{name: ANSIBLE_REMOTE_TEMP}, {name: ANSIBLE_REMOTE_TMP}] + ini: + - section: defaults + key: remote_tmp + vars: + - name: ansible_remote_tmp + common_remote_group: + name: Enables changing the group ownership of temporary files and directories + default: null + description: + - Checked when Ansible needs to execute a module as a different user. + - If setfacl and chown both fail and do not let the different user access the module's files, they will be chgrp'd to this group. + - In order for this to work, the remote_user and become_user must share a common group and this setting must be set to that group. + env: [{name: ANSIBLE_COMMON_REMOTE_GROUP}] + vars: + - name: ansible_common_remote_group + ini: + - {key: common_remote_group, section: defaults} + version_added: "2.10" + system_tmpdirs: + description: + - "List of valid system temporary directories on the managed machine for Ansible to validate + C(remote_tmp) against, when specific permissions are needed. These must be world + readable, writable, and executable. This list should only contain directories which the + system administrator has pre-created with the proper ownership and permissions otherwise + security issues can arise." + - When C(remote_tmp) is required to be a system temp dir and it does not match any in the list, + the first one from the list will be used instead. + default: [ /var/tmp, /tmp ] + type: list + elements: string + env: [{name: ANSIBLE_SYSTEM_TMPDIRS}] + ini: + - section: defaults + key: system_tmpdirs + vars: + - name: ansible_system_tmpdirs + async_dir: + description: + - Directory in which ansible will keep async job information + default: '~/.ansible_async' + env: [{name: ANSIBLE_ASYNC_DIR}] + ini: + - section: defaults + key: async_dir + vars: + - name: ansible_async_dir + environment: + type: list + elements: dictionary + default: [{}] + description: + - List of dictionaries of environment variables and their values to use when executing commands. + keyword: + - name: environment + admin_users: + type: list + elements: string + default: ['root', 'toor'] + description: + - list of users to be expected to have admin privileges. This is used by the controller to + determine how to share temporary files between the remote user and the become user. + env: + - name: ANSIBLE_ADMIN_USERS + ini: + - section: defaults + key: admin_users + vars: + - name: ansible_admin_users + world_readable_temp: + version_added: '2.10' + default: False + description: + - This makes the temporary files created on the machine world-readable and will issue a warning instead of failing the task. + - It is useful when becoming an unprivileged user. + env: + - name: ANSIBLE_SHELL_ALLOW_WORLD_READABLE_TEMP + vars: + - name: ansible_shell_allow_world_readable_temp + ini: + - {key: allow_world_readable_tmpfiles, section: defaults} + type: boolean +""" diff --git a/lib/ansible/plugins/doc_fragments/shell_windows.py b/lib/ansible/plugins/doc_fragments/shell_windows.py new file mode 100644 index 0000000..ac52c60 --- /dev/null +++ b/lib/ansible/plugins/doc_fragments/shell_windows.py @@ -0,0 +1,51 @@ +# Copyright (c) 2019 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + + +class ModuleDocFragment(object): + + # Windows shell documentation fragment + # FIXME: set_module_language don't belong here but must be set so they don't fail when someone + # get_option('set_module_language') on this plugin + DOCUMENTATION = r""" +options: + async_dir: + description: + - Directory in which ansible will keep async job information. + - Before Ansible 2.8, this was set to C(remote_tmp + "\.ansible_async"). + default: '%USERPROFILE%\.ansible_async' + ini: + - section: powershell + key: async_dir + vars: + - name: ansible_async_dir + version_added: '2.8' + remote_tmp: + description: + - Temporary directory to use on targets when copying files to the host. + default: '%TEMP%' + ini: + - section: powershell + key: remote_tmp + vars: + - name: ansible_remote_tmp + set_module_language: + description: + - Controls if we set the locale for modules when executing on the + target. + - Windows only supports C(no) as an option. + type: bool + default: 'no' + choices: ['no', False] + environment: + description: + - List of dictionaries of environment variables and their values to use when + executing commands. + keyword: + - name: environment + type: list + elements: dictionary + default: [{}] +""" diff --git a/lib/ansible/plugins/doc_fragments/template_common.py b/lib/ansible/plugins/doc_fragments/template_common.py new file mode 100644 index 0000000..6276e84 --- /dev/null +++ b/lib/ansible/plugins/doc_fragments/template_common.py @@ -0,0 +1,121 @@ +# -*- coding: utf-8 -*- + +# Copyright (c) 2019 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + + +class ModuleDocFragment(object): + + # Standard template documentation fragment, use by template and win_template. + DOCUMENTATION = r''' +description: +- Templates are processed by the L(Jinja2 templating language,http://jinja.pocoo.org/docs/). +- Documentation on the template formatting can be found in the + L(Template Designer Documentation,http://jinja.pocoo.org/docs/templates/). +- Additional variables listed below can be used in templates. +- C(ansible_managed) (configurable via the C(defaults) section of C(ansible.cfg)) contains a string which can be used to + describe the template name, host, modification time of the template file and the owner uid. +- C(template_host) contains the node name of the template's machine. +- C(template_uid) is the numeric user id of the owner. +- C(template_path) is the path of the template. +- C(template_fullpath) is the absolute path of the template. +- C(template_destpath) is the path of the template on the remote system (added in 2.8). +- C(template_run_date) is the date that the template was rendered. +options: + src: + description: + - Path of a Jinja2 formatted template on the Ansible controller. + - This can be a relative or an absolute path. + - The file must be encoded with C(utf-8) but I(output_encoding) can be used to control the encoding of the output + template. + type: path + required: yes + dest: + description: + - Location to render the template to on the remote machine. + type: path + required: yes + newline_sequence: + description: + - Specify the newline sequence to use for templating files. + type: str + choices: [ '\n', '\r', '\r\n' ] + default: '\n' + version_added: '2.4' + block_start_string: + description: + - The string marking the beginning of a block. + type: str + default: '{%' + version_added: '2.4' + block_end_string: + description: + - The string marking the end of a block. + type: str + default: '%}' + version_added: '2.4' + variable_start_string: + description: + - The string marking the beginning of a print statement. + type: str + default: '{{' + version_added: '2.4' + variable_end_string: + description: + - The string marking the end of a print statement. + type: str + default: '}}' + version_added: '2.4' + comment_start_string: + description: + - The string marking the beginning of a comment statement. + type: str + version_added: '2.12' + comment_end_string: + description: + - The string marking the end of a comment statement. + type: str + version_added: '2.12' + trim_blocks: + description: + - Determine when newlines should be removed from blocks. + - When set to C(yes) the first newline after a block is removed (block, not variable tag!). + type: bool + default: yes + version_added: '2.4' + lstrip_blocks: + description: + - Determine when leading spaces and tabs should be stripped. + - When set to C(yes) leading spaces and tabs are stripped from the start of a line to a block. + type: bool + default: no + version_added: '2.6' + force: + description: + - Determine when the file is being transferred if the destination already exists. + - When set to C(yes), replace the remote file when contents are different than the source. + - When set to C(no), the file will only be transferred if the destination does not exist. + type: bool + default: yes + output_encoding: + description: + - Overrides the encoding used to write the template file defined by C(dest). + - It defaults to C(utf-8), but any encoding supported by python can be used. + - The source template file must always be encoded using C(utf-8), for homogeneity. + type: str + default: utf-8 + version_added: '2.7' +notes: +- Including a string that uses a date in the template will result in the template being marked 'changed' each time. +- Since Ansible 0.9, templates are loaded with C(trim_blocks=True). +- > + Also, you can override jinja2 settings by adding a special header to template file. + i.e. C(#jinja2:variable_start_string:'[%', variable_end_string:'%]', trim_blocks: False) + which changes the variable interpolation markers to C([% var %]) instead of C({{ var }}). + This is the best way to prevent evaluation of things that look like, but should not be Jinja2. +- To find Byte Order Marks in files, use C(Format-Hex <file> -Count 16) on Windows, and use C(od -a -t x1 -N 16 <file>) + on Linux. +''' diff --git a/lib/ansible/plugins/doc_fragments/url.py b/lib/ansible/plugins/doc_fragments/url.py new file mode 100644 index 0000000..eb2b17f --- /dev/null +++ b/lib/ansible/plugins/doc_fragments/url.py @@ -0,0 +1,75 @@ +# -*- coding: utf-8 -*- + +# Copyright: (c) 2018, John Barker <gundalow@redhat.com> +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + + +class ModuleDocFragment(object): + + # Standard files documentation fragment + DOCUMENTATION = r''' +options: + url: + description: + - HTTP, HTTPS, or FTP URL in the form (http|https|ftp)://[user[:pass]]@host.domain[:port]/path + type: str + force: + description: + - If C(yes) do not get a cached copy. + type: bool + default: no + http_agent: + description: + - Header to identify as, generally appears in web server logs. + type: str + default: ansible-httpget + use_proxy: + description: + - If C(no), it will not use a proxy, even if one is defined in an environment variable on the target hosts. + type: bool + default: yes + validate_certs: + description: + - If C(no), SSL certificates will not be validated. + - This should only be used on personally controlled sites using self-signed certificates. + type: bool + default: yes + url_username: + description: + - The username for use in HTTP basic authentication. + - This parameter can be used without I(url_password) for sites that allow empty passwords + type: str + url_password: + description: + - The password for use in HTTP basic authentication. + - If the I(url_username) parameter is not specified, the I(url_password) parameter will not be used. + type: str + force_basic_auth: + description: + - Credentials specified with I(url_username) and I(url_password) should be passed in HTTP Header. + type: bool + default: no + client_cert: + description: + - PEM formatted certificate chain file to be used for SSL client authentication. + - This file can also include the key as well, and if the key is included, C(client_key) is not required. + type: path + client_key: + description: + - PEM formatted file that contains your private key to be used for SSL client authentication. + - If C(client_cert) contains both the certificate and key, this option is not required. + type: path + use_gssapi: + description: + - Use GSSAPI to perform the authentication, typically this is for Kerberos or Kerberos through Negotiate + authentication. + - Requires the Python library L(gssapi,https://github.com/pythongssapi/python-gssapi) to be installed. + - Credentials for GSSAPI can be specified with I(url_username)/I(url_password) or with the GSSAPI env var + C(KRB5CCNAME) that specified a custom Kerberos credential cache. + - NTLM authentication is C(not) supported even if the GSSAPI mech for NTLM has been installed. + type: bool + default: no + version_added: '2.11' +''' diff --git a/lib/ansible/plugins/doc_fragments/url_windows.py b/lib/ansible/plugins/doc_fragments/url_windows.py new file mode 100644 index 0000000..286f4b4 --- /dev/null +++ b/lib/ansible/plugins/doc_fragments/url_windows.py @@ -0,0 +1,150 @@ +# -*- coding: utf-8 -*- + +# Copyright (c) 2019 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + + +class ModuleDocFragment: + + # Common options for Ansible.ModuleUtils.WebRequest + DOCUMENTATION = r''' +options: + method: + description: + - The HTTP Method of the request. + type: str + follow_redirects: + description: + - Whether or the module should follow redirects. + - C(all) will follow all redirect. + - C(none) will not follow any redirect. + - C(safe) will follow only "safe" redirects, where "safe" means that the + client is only doing a C(GET) or C(HEAD) on the URI to which it is being + redirected. + - When following a redirected URL, the C(Authorization) header and any + credentials set will be dropped and not redirected. + choices: + - all + - none + - safe + default: safe + type: str + headers: + description: + - Extra headers to set on the request. + - This should be a dictionary where the key is the header name and the + value is the value for that header. + type: dict + http_agent: + description: + - Header to identify as, generally appears in web server logs. + - This is set to the C(User-Agent) header on a HTTP request. + default: ansible-httpget + type: str + maximum_redirection: + description: + - Specify how many times the module will redirect a connection to an + alternative URI before the connection fails. + - If set to C(0) or I(follow_redirects) is set to C(none), or C(safe) when + not doing a C(GET) or C(HEAD) it prevents all redirection. + default: 50 + type: int + timeout: + description: + - Specifies how long the request can be pending before it times out (in + seconds). + - Set to C(0) to specify an infinite timeout. + default: 30 + type: int + validate_certs: + description: + - If C(no), SSL certificates will not be validated. + - This should only be used on personally controlled sites using self-signed + certificates. + default: yes + type: bool + client_cert: + description: + - The path to the client certificate (.pfx) that is used for X509 + authentication. This path can either be the path to the C(pfx) on the + filesystem or the PowerShell certificate path + C(Cert:\CurrentUser\My\<thumbprint>). + - The WinRM connection must be authenticated with C(CredSSP) or C(become) + is used on the task if the certificate file is not password protected. + - Other authentication types can set I(client_cert_password) when the cert + is password protected. + type: str + client_cert_password: + description: + - The password for I(client_cert) if the cert is password protected. + type: str + force_basic_auth: + description: + - By default the authentication header is only sent when a webservice + responses to an initial request with a 401 status. Since some basic auth + services do not properly send a 401, logins will fail. + - This option forces the sending of the Basic authentication header upon + the original request. + default: no + type: bool + url_username: + description: + - The username to use for authentication. + type: str + url_password: + description: + - The password for I(url_username). + type: str + use_default_credential: + description: + - Uses the current user's credentials when authenticating with a server + protected with C(NTLM), C(Kerberos), or C(Negotiate) authentication. + - Sites that use C(Basic) auth will still require explicit credentials + through the I(url_username) and I(url_password) options. + - The module will only have access to the user's credentials if using + C(become) with a password, you are connecting with SSH using a password, + or connecting with WinRM using C(CredSSP) or C(Kerberos with delegation). + - If not using C(become) or a different auth method to the ones stated + above, there will be no default credentials available and no + authentication will occur. + default: no + type: bool + use_proxy: + description: + - If C(no), it will not use the proxy defined in IE for the current user. + default: yes + type: bool + proxy_url: + description: + - An explicit proxy to use for the request. + - By default, the request will use the IE defined proxy unless I(use_proxy) + is set to C(no). + type: str + proxy_username: + description: + - The username to use for proxy authentication. + type: str + proxy_password: + description: + - The password for I(proxy_username). + type: str + proxy_use_default_credential: + description: + - Uses the current user's credentials when authenticating with a proxy host + protected with C(NTLM), C(Kerberos), or C(Negotiate) authentication. + - Proxies that use C(Basic) auth will still require explicit credentials + through the I(proxy_username) and I(proxy_password) options. + - The module will only have access to the user's credentials if using + C(become) with a password, you are connecting with SSH using a password, + or connecting with WinRM using C(CredSSP) or C(Kerberos with delegation). + - If not using C(become) or a different auth method to the ones stated + above, there will be no default credentials available and no proxy + authentication will occur. + default: no + type: bool +seealso: +- module: community.windows.win_inet_proxy +''' diff --git a/lib/ansible/plugins/doc_fragments/validate.py b/lib/ansible/plugins/doc_fragments/validate.py new file mode 100644 index 0000000..ac66d25 --- /dev/null +++ b/lib/ansible/plugins/doc_fragments/validate.py @@ -0,0 +1,21 @@ +# -*- coding: utf-8 -*- + +# Copyright: (c) 2015, Ansible, Inc +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + + +class ModuleDocFragment(object): + # Standard documentation fragment + DOCUMENTATION = r''' +options: + validate: + description: + - The validation command to run before copying the updated file into the final destination. + - A temporary file path is used to validate, passed in through '%s' which must be present as in the examples below. + - Also, the command is passed securely so shell features such as expansion and pipes will not work. + - For an example on how to handle more complex validation than what this + option provides, see R(handling complex validation,complex_configuration_validation). + type: str +''' diff --git a/lib/ansible/plugins/doc_fragments/vars_plugin_staging.py b/lib/ansible/plugins/doc_fragments/vars_plugin_staging.py new file mode 100644 index 0000000..b2da29c --- /dev/null +++ b/lib/ansible/plugins/doc_fragments/vars_plugin_staging.py @@ -0,0 +1,24 @@ +# -*- coding: utf-8 -*- + +# Copyright: (c) 2019, Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +class ModuleDocFragment(object): + + DOCUMENTATION = r''' +options: + stage: + description: + - Control when this vars plugin may be executed. + - Setting this option to C(all) will run the vars plugin after importing inventory and whenever it is demanded by a task. + - Setting this option to C(task) will only run the vars plugin whenever it is demanded by a task. + - Setting this option to C(inventory) will only run the vars plugin after parsing inventory. + - If this option is omitted, the global I(RUN_VARS_PLUGINS) configuration is used to determine when to execute the vars plugin. + choices: ['all', 'task', 'inventory'] + version_added: "2.10" + type: str +''' |