diff --git a/lib/ansible/modules/cron.py b/lib/ansible/modules/cron.py index 93277a49ef4..2424f5c0655 100644 --- a/lib/ansible/modules/cron.py +++ b/lib/ansible/modules/cron.py @@ -33,8 +33,8 @@ options: name: description: - Description of a crontab entry or, if env is set, the name of environment variable. - - Required if C(state=absent). - - Note that if name is not set and C(state=present), then a + - Required if I(state=absent). + - Note that if name is not set and I(state=present), then a new crontab entry will always be created, regardless of existing ones. - This parameter will always be required in future releases. type: str @@ -47,7 +47,7 @@ options: description: - The command to execute or, if env is set, the value of environment variable. - The command should not contain line breaks. - - Required if C(state=present). + - Required if I(state=present). type: str aliases: [ value ] state: @@ -60,10 +60,10 @@ options: description: - If specified, uses this file instead of an individual user's crontab. - If this is a relative path, it is interpreted with respect to I(/etc/cron.d). - - If it is absolute, it will typically be I(/etc/crontab). + - If it is absolute, it will typically be C(/etc/crontab). - Many linux distros expect (and some require) the filename portion to consist solely of upper- and lower-case letters, digits, underscores, and hyphens. - - To use the C(cron_file) parameter you must specify the C(user) as well. + - To use the I(cron_file) parameter you must specify the I(user) as well. type: str backup: description: @@ -73,34 +73,34 @@ options: default: no minute: description: - - Minute when the job should run ( 0-59, *, */2, etc ) + - Minute when the job should run (C(0-59), C(*), C(*/2), and so on). type: str default: "*" hour: description: - - Hour when the job should run ( 0-23, *, */2, etc ) + - Hour when the job should run (C(0-23), C(*), C(*/2), and so on). type: str default: "*" day: description: - - Day of the month the job should run ( 1-31, *, */2, etc ) + - Day of the month the job should run (C(1-31), C(*), C(*/2), and so on). type: str default: "*" aliases: [ dom ] month: description: - - Month of the year the job should run ( 1-12, *, */2, etc ) + - Month of the year the job should run (C(1-12), C(*), C(*/2), and so on). type: str default: "*" weekday: description: - - Day of the week that the job should run ( 0-6 for Sunday-Saturday, *, etc ) + - Day of the week that the job should run (C(0-6) for Sunday-Saturday, C(*), and so on). type: str default: "*" aliases: [ dow ] reboot: description: - - If the job should be run at reboot. This option is deprecated. Users should use special_time. + - If the job should be run at reboot. This option is deprecated. Users should use I(special_time). version_added: "1.0" type: bool default: no @@ -113,7 +113,7 @@ options: disabled: description: - If the job should be disabled (commented out) in the crontab. - - Only has effect if C(state=present). + - Only has effect if I(state=present). type: bool default: no version_added: "2.0" @@ -121,66 +121,68 @@ options: description: - If set, manages a crontab's environment variable. - New variables are added on top of crontab. - - C(name) and C(value) parameters are the name and the value of environment variable. + - I(name) and I(value) parameters are the name and the value of environment variable. type: bool default: false version_added: "2.1" insertafter: description: - - Used with C(state=present) and C(env). + - Used with I(state=present) and I(env). - If specified, the environment variable will be inserted after the declaration of specified environment variable. type: str version_added: "2.1" insertbefore: description: - - Used with C(state=present) and C(env). + - Used with I(state=present) and I(env). - If specified, the environment variable will be inserted before the declaration of specified environment variable. type: str version_added: "2.1" requirements: - cron (or cronie on CentOS) author: - - Dane Summers (@dsummersl) - - Mike Grozak (@rhaido) - - Patrick Callahan (@dirtyharrycallahan) - - Evan Kaufman (@EvanK) - - Luca Berruti (@lberruti) + - Dane Summers (@dsummersl) + - Mike Grozak (@rhaido) + - Patrick Callahan (@dirtyharrycallahan) + - Evan Kaufman (@EvanK) + - Luca Berruti (@lberruti) +notes: + - Supports C(check_mode). ''' EXAMPLES = r''' - name: Ensure a job that runs at 2 and 5 exists. Creates an entry like "0 5,2 * * ls -alh > /dev/null" - cron: + ansible.builtin.cron: name: "check dirs" minute: "0" hour: "5,2" job: "ls -alh > /dev/null" - name: 'Ensure an old job is no longer present. Removes any job that is prefixed by "#Ansible: an old job" from the crontab' - cron: + ansible.builtin.cron: name: "an old job" state: absent - name: Creates an entry like "@reboot /some/job.sh" - cron: + ansible.builtin.cron: name: "a job for reboot" special_time: reboot job: "/some/job.sh" - name: Creates an entry like "PATH=/opt/bin" on top of crontab - cron: + ansible.builtin.cron: name: PATH env: yes job: /opt/bin - name: Creates an entry like "APP_HOME=/srv/app" and insert it after PATH declaration - cron: + ansible.builtin.cron: name: APP_HOME env: yes job: /srv/app insertafter: PATH - name: Creates a cron file under /etc/cron.d - cron: + ansible.builtin.cron: name: yum autoupdate weekday: "2" minute: "0" @@ -190,18 +192,20 @@ EXAMPLES = r''' cron_file: ansible_yum-autoupdate - name: Removes a cron file from under /etc/cron.d - cron: + ansible.builtin.cron: name: "yum autoupdate" cron_file: ansible_yum-autoupdate state: absent - name: Removes "APP_HOME" environment variable from crontab - cron: + ansible.builtin.cron: name: APP_HOME env: yes state: absent ''' +RETURN = r'''#''' + import os import platform import pwd diff --git a/lib/ansible/modules/debconf.py b/lib/ansible/modules/debconf.py index 8dbb30d3b69..dd6cd63510a 100644 --- a/lib/ansible/modules/debconf.py +++ b/lib/ansible/modules/debconf.py @@ -23,6 +23,7 @@ notes: installed to see questions/settings available. - Some distros will always record tasks involving the setting of passwords as changed. This is due to debconf-get-selections masking passwords. - It is highly recommended to add I(no_log=True) to task while handling sensitive information using this module. + - Supports C(check_mode). requirements: - debconf - debconf-utils @@ -61,32 +62,32 @@ author: EXAMPLES = r''' - name: Set default locale to fr_FR.UTF-8 - debconf: + ansible.builtin.debconf: name: locales question: locales/default_environment_locale value: fr_FR.UTF-8 vtype: select - name: Set to generate locales - debconf: + ansible.builtin.debconf: name: locales question: locales/locales_to_be_generated value: en_US.UTF-8 UTF-8, fr_FR.UTF-8 UTF-8 vtype: multiselect - name: Accept oracle license - debconf: + ansible.builtin.debconf: name: oracle-java7-installer question: shared/accepted-oracle-license-v1-1 value: 'true' vtype: select - name: Specifying package you can register/return the list of questions and current values - debconf: + ansible.builtin.debconf: name: tzdata - name: Pre-configure tripwire site passphrase - debconf: + ansible.builtin.debconf: name: tripwire question: tripwire/site-passphrase value: "{{ site_passphrase }}" @@ -94,6 +95,8 @@ EXAMPLES = r''' no_log: True ''' +RETURN = r'''#''' + from ansible.module_utils._text import to_text from ansible.module_utils.basic import AnsibleModule diff --git a/lib/ansible/modules/debug.py b/lib/ansible/modules/debug.py index bd8eb7e26e5..86c4b951749 100644 --- a/lib/ansible/modules/debug.py +++ b/lib/ansible/modules/debug.py @@ -49,29 +49,27 @@ author: ''' EXAMPLES = r''' -# Example that prints the loopback address and gateway for each host -- debug: - msg: System {{ inventory_hostname }} has uuid {{ ansible_product_uuid }} - -- debug: +- name: Print the gateway for each host when defined + ansible.builtin.debug: msg: System {{ inventory_hostname }} has gateway {{ ansible_default_ipv4.gateway }} when: ansible_default_ipv4.gateway is defined -# Example that prints return information from the previous task -- shell: /usr/bin/uptime +- name: Get uptime information + ansible.builtin.shell: /usr/bin/uptime register: result -- debug: +- name: Print return information from the previous task + ansible.builtin.debug: var: result verbosity: 2 - name: Display all variables/facts known for a host - debug: + ansible.builtin.debug: var: hostvars[inventory_hostname] verbosity: 4 -# Example that prints two lines of messages, but only if there is an environment value set -- debug: +- name: Prints two lines of messages, but only if there is an environment value set + ansible.builtin.debug: msg: - "Provisioning based on YOUR_KEY which is: {{ lookup('env', 'YOUR_KEY') }}" - "These servers were built using the password of '{{ password_used }}'. Please retain this for later use." diff --git a/lib/ansible/modules/fetch.py b/lib/ansible/modules/fetch.py index d2f886dc8db..0c25a2021df 100644 --- a/lib/ansible/modules/fetch.py +++ b/lib/ansible/modules/fetch.py @@ -71,6 +71,7 @@ notes: also explicitly set C(fail_on_missing) to C(no) to get the non-failing behaviour. - This module is also supported for Windows targets. +- Supports C(check_mode). seealso: - module: ansible.builtin.copy - module: ansible.builtin.slurp @@ -81,24 +82,24 @@ author: EXAMPLES = r''' - name: Store file into /tmp/fetched/host.example.com/tmp/somefile - fetch: + ansible.builtin.fetch: src: /tmp/somefile dest: /tmp/fetched - name: Specifying a path directly - fetch: + ansible.builtin.fetch: src: /tmp/somefile dest: /tmp/prefix-{{ inventory_hostname }} flat: yes - name: Specifying a destination path - fetch: + ansible.builtin.fetch: src: /tmp/uniquefile dest: /tmp/special/ flat: yes - name: Storing in a path relative to the playbook - fetch: + ansible.builtin.fetch: src: /tmp/uniquefile dest: special/prefix-{{ inventory_hostname }} flat: yes diff --git a/lib/ansible/modules/group.py b/lib/ansible/modules/group.py index 5c25d86f502..1deb967afe3 100644 --- a/lib/ansible/modules/group.py +++ b/lib/ansible/modules/group.py @@ -62,20 +62,21 @@ seealso: - module: ansible.windows.win_group author: - Stephen Fromm (@sfromm) +notes: +- Supports C(check_mode). ''' EXAMPLES = ''' - name: Ensure group "somegroup" exists - group: + ansible.builtin.group: name: somegroup state: present - name: Ensure group "docker" exists with correct gid - group: + ansible.builtin.group: name: docker state: present gid: 1750 - ''' RETURN = r''' @@ -85,17 +86,17 @@ gid: type: int sample: 1001 name: - description: Group name + description: Group name. returned: always type: str sample: users state: - description: Whether the group is present or not + description: Whether the group is present or not. returned: always type: str sample: 'absent' system: - description: Whether the group is a system group or not + description: Whether the group is a system group or not. returned: When C(state) is 'present' type: bool sample: False diff --git a/lib/ansible/modules/lineinfile.py b/lib/ansible/modules/lineinfile.py index 4e856e50842..7b3644991ac 100644 --- a/lib/ansible/modules/lineinfile.py +++ b/lib/ansible/modules/lineinfile.py @@ -125,6 +125,7 @@ extends_documentation_fragment: - validate notes: - As of Ansible 2.3, the I(dest) option has been changed to I(path) as default, but I(dest) still works as well. + - Supports C(check_mode). seealso: - module: ansible.builtin.blockinfile - module: ansible.builtin.copy @@ -140,19 +141,19 @@ author: EXAMPLES = r''' # NOTE: Before 2.3, option 'dest', 'destfile' or 'name' was used instead of 'path' - name: Ensure SELinux is set to enforcing mode - lineinfile: + ansible.builtin.lineinfile: path: /etc/selinux/config regexp: '^SELINUX=' line: SELINUX=enforcing - name: Make sure group wheel is not in the sudoers configuration - lineinfile: + ansible.builtin.lineinfile: path: /etc/sudoers state: absent regexp: '^%wheel' - name: Replace a localhost entry with our own - lineinfile: + ansible.builtin.lineinfile: path: /etc/hosts regexp: '^127\.0\.0\.1' line: 127.0.0.1 localhost @@ -161,28 +162,28 @@ EXAMPLES = r''' mode: '0644' - name: Ensure the default Apache port is 8080 - lineinfile: + ansible.builtin.lineinfile: path: /etc/httpd/conf/httpd.conf regexp: '^Listen ' insertafter: '^#Listen ' line: Listen 8080 - name: Ensure we have our own comment added to /etc/services - lineinfile: + ansible.builtin.lineinfile: path: /etc/services regexp: '^# port for http' insertbefore: '^www.*80/tcp' line: '# port for http by default' - name: Add a line to a file if the file does not exist, without passing regexp - lineinfile: + ansible.builtin.lineinfile: path: /tmp/testfile line: 192.168.1.99 foo.lab.net foo create: yes # NOTE: Yaml requires escaping backslashes in double quotes but not in single quotes - name: Ensure the JBoss memory settings are exactly as needed - lineinfile: + ansible.builtin.lineinfile: path: /opt/jboss-as/bin/standalone.conf regexp: '^(.*)Xms(\d+)m(.*)$' line: '\1Xms${xms}m\3' @@ -190,7 +191,7 @@ EXAMPLES = r''' # NOTE: Fully quoted because of the ': ' on the line. See the Gotchas in the YAML docs. - name: Validate the sudoers file before saving - lineinfile: + ansible.builtin.lineinfile: path: /etc/sudoers state: present regexp: '^%ADMIN ALL=' @@ -199,13 +200,15 @@ EXAMPLES = r''' # See https://docs.python.org/3/library/re.html for further details on syntax - name: Use backrefs with alternative group syntax to avoid conflicts with variable values - lineinfile: + ansible.builtin.lineinfile: path: /tmp/config regexp: ^(host=).* line: \g<1>{{ hostname }} backrefs: yes ''' +RETURN = r'''#''' + import os import re import tempfile diff --git a/lib/ansible/modules/ping.py b/lib/ansible/modules/ping.py index fe9238f62a7..2cb1fb231f2 100644 --- a/lib/ansible/modules/ping.py +++ b/lib/ansible/modules/ping.py @@ -15,12 +15,12 @@ module: ping version_added: historical short_description: Try to connect to host, verify a usable python and return C(pong) on success description: - - A trivial test module, this module always returns C(pong) on successful - contact. It does not make sense in playbooks, but it is useful from - C(/usr/bin/ansible) to verify the ability to login and that a usable Python is configured. - - This is NOT ICMP ping, this is just a trivial test module that requires Python on the remote-node. - - For Windows targets, use the M(ansible.windows.win_ping) module instead. - - For Network targets, use the M(ansible.netcommon.net_ping) module instead. + - A trivial test module, this module always returns C(pong) on successful + contact. It does not make sense in playbooks, but it is useful from + C(/usr/bin/ansible) to verify the ability to login and that a usable Python is configured. + - This is NOT ICMP ping, this is just a trivial test module that requires Python on the remote-node. + - For Windows targets, use the M(ansible.windows.win_ping) module instead. + - For Network targets, use the M(ansible.netcommon.net_ping) module instead. options: data: description: @@ -29,11 +29,13 @@ options: type: str default: pong seealso: -- module: ansible.netcommon.net_ping -- module: ansible.windows.win_ping + - module: ansible.netcommon.net_ping + - module: ansible.windows.win_ping author: - - Ansible Core Team - - Michael DeHaan + - Ansible Core Team + - Michael DeHaan +notes: + - Supports C(check_mode). ''' EXAMPLES = ''' @@ -41,16 +43,16 @@ EXAMPLES = ''' # ansible webservers -m ping - name: Example from an Ansible Playbook - ping: + ansible.builtin.ping: - name: Induce an exception to see what happens - ping: + ansible.builtin.ping: data: crash ''' RETURN = ''' ping: - description: value provided with the data parameter + description: Value provided with the data parameter. returned: success type: str sample: pong diff --git a/lib/ansible/modules/replace.py b/lib/ansible/modules/replace.py index a694d9e7655..ed9fd1f2873 100644 --- a/lib/ansible/modules/replace.py +++ b/lib/ansible/modules/replace.py @@ -95,24 +95,25 @@ notes: previous incorrect behavior, you may be need to adjust your tasks. See U(https://github.com/ansible/ansible/issues/31354) for details. - Option I(follow) has been removed in Ansible 2.5, because this module modifies the contents of the file so I(follow=no) doesn't make sense. + - Supports C(check_mode). ''' EXAMPLES = r''' - name: Before Ansible 2.3, option 'dest', 'destfile' or 'name' was used instead of 'path' - replace: + ansible.builtin.replace: path: /etc/hosts regexp: '(\s+)old\.host\.name(\s+.*)?$' replace: '\1new.host.name\2' - name: Replace after the expression till the end of the file (requires Ansible >= 2.4) - replace: + ansible.builtin.replace: path: /etc/apache2/sites-available/default.conf after: 'NameVirtualHost [*]' regexp: '^(.+)$' replace: '# \1' - name: Replace before the expression till the begin of the file (requires Ansible >= 2.4) - replace: + ansible.builtin.replace: path: /etc/apache2/sites-available/default.conf before: '# live site config' regexp: '^(.+)$' @@ -121,7 +122,7 @@ EXAMPLES = r''' # Prior to Ansible 2.7.10, using before and after in combination did the opposite of what was intended. # see https://github.com/ansible/ansible/issues/31354 for details. - name: Replace between the expressions (requires Ansible >= 2.4) - replace: + ansible.builtin.replace: path: /etc/hosts after: '' before: '' @@ -129,7 +130,7 @@ EXAMPLES = r''' replace: '# \1' - name: Supports common file attributes - replace: + ansible.builtin.replace: path: /home/jdoe/.ssh/known_hosts regexp: '^old\.host\.name[^\n]*\n' owner: jdoe @@ -137,34 +138,36 @@ EXAMPLES = r''' mode: '0644' - name: Supports a validate command - replace: + ansible.builtin.replace: path: /etc/apache/ports regexp: '^(NameVirtualHost|Listen)\s+80\s*$' replace: '\1 127.0.0.1:8080' validate: '/usr/sbin/apache2ctl -f %s -t' - name: Short form task (in ansible 2+) necessitates backslash-escaped sequences - replace: path=/etc/hosts regexp='\\b(localhost)(\\d*)\\b' replace='\\1\\2.localdomain\\2 \\1\\2' + ansible.builtin.replace: path=/etc/hosts regexp='\\b(localhost)(\\d*)\\b' replace='\\1\\2.localdomain\\2 \\1\\2' - name: Long form task does not - replace: + ansible.builtin.replace: path: /etc/hosts regexp: '\b(localhost)(\d*)\b' replace: '\1\2.localdomain\2 \1\2' - name: Explicitly specifying positional matched groups in replacement - replace: + ansible.builtin.replace: path: /etc/ssh/sshd_config regexp: '^(ListenAddress[ ]+)[^\n]+$' replace: '\g<1>0.0.0.0' - name: Explicitly specifying named matched groups - replace: + ansible.builtin.replace: path: /etc/ssh/sshd_config regexp: '^(?PListenAddress[ ]+)(?P[^\n]+)$' replace: '#\g\g\n\g0.0.0.0' ''' +RETURN = r'''#''' + import os import re import tempfile diff --git a/lib/ansible/modules/script.py b/lib/ansible/modules/script.py index 3e013820d8e..4333edfac22 100644 --- a/lib/ansible/modules/script.py +++ b/lib/ansible/modules/script.py @@ -11,12 +11,12 @@ module: script version_added: "0.9" short_description: Runs a local script on a remote node after transferring it description: - - The C(script) module takes the script name followed by a list of space-delimited arguments. - - Either a free form command or C(cmd) parameter is required, see the examples. - - The local script at path will be transferred to the remote node and then executed. - - The given script will be processed through the shell environment on the remote node. - - This module does not require python on the remote system, much like the M(ansible.builtin.raw) module. - - This module is also supported for Windows targets. + - The C(script) module takes the script name followed by a list of space-delimited arguments. + - Either a free form command or C(cmd) parameter is required, see the examples. + - The local script at path will be transferred to the remote node and then executed. + - The given script will be processed through the shell environment on the remote node. + - This module does not require python on the remote system, much like the M(ansible.builtin.raw) module. + - This module is also supported for Windows targets. options: free_form: description: @@ -47,41 +47,42 @@ notes: stderr is sent to stdout. If you depend on separated stdout and stderr result keys, please switch to a copy+command set of tasks instead of using script. - If the path to the local script contains spaces, it needs to be quoted. - This module is also supported for Windows targets. + - Does not support C(check_mode). seealso: -- module: ansible.builtin.shell -- module: ansible.windows.win_shell + - module: ansible.builtin.shell + - module: ansible.windows.win_shell author: - - Ansible Core Team - - Michael DeHaan + - Ansible Core Team + - Michael DeHaan extends_documentation_fragment: - - decrypt + - decrypt ''' EXAMPLES = r''' - name: Run a script with arguments (free form) - script: /some/local/script.sh --some-argument 1234 + ansible.builtin.script: /some/local/script.sh --some-argument 1234 - name: Run a script with arguments (using 'cmd' parameter) - script: + ansible.builtin.script: cmd: /some/local/script.sh --some-argument 1234 - name: Run a script only if file.txt does not exist on the remote node - script: /some/local/create_file.sh --some-argument 1234 + ansible.builtin.script: /some/local/create_file.sh --some-argument 1234 args: creates: /the/created/file.txt - name: Run a script only if file.txt exists on the remote node - script: /some/local/remove_file.sh --some-argument 1234 + ansible.builtin.script: /some/local/remove_file.sh --some-argument 1234 args: removes: /the/removed/file.txt - name: Run a script using an executable in a non-system path - script: /some/local/script + ansible.builtin.script: /some/local/script args: executable: /some/remote/executable - name: Run a script using an executable in a system path - script: /some/local/script.py + ansible.builtin.script: /some/local/script.py args: executable: python3 ''' diff --git a/lib/ansible/modules/service.py b/lib/ansible/modules/service.py index 8ed03618704..f4eb709735d 100644 --- a/lib/ansible/modules/service.py +++ b/lib/ansible/modules/service.py @@ -79,8 +79,9 @@ options: version_added: 2.2 notes: - For AIX, group subsystem names can be used. + - Supports C(check_mode). seealso: -- module: ansible.windows.win_service + - module: ansible.windows.win_service author: - Ansible Core Team - Michael DeHaan @@ -88,43 +89,45 @@ author: EXAMPLES = r''' - name: Start service httpd, if not started - service: + ansible.builtin.service: name: httpd state: started - name: Stop service httpd, if started - service: + ansible.builtin.service: name: httpd state: stopped - name: Restart service httpd, in all cases - service: + ansible.builtin.service: name: httpd state: restarted - name: Reload service httpd, in all cases - service: + ansible.builtin.service: name: httpd state: reloaded - name: Enable service httpd, and not touch the state - service: + ansible.builtin.service: name: httpd enabled: yes - name: Start service foo, based on running process /usr/bin/foo - service: + ansible.builtin.service: name: foo pattern: /usr/bin/foo state: started - name: Restart network service for interface eth0 - service: + ansible.builtin.service: name: network state: restarted args: eth0 ''' +RETURN = r'''#''' + import glob import json import os