ansible-core 2.17.6rc1__py3-none-any.whl → 2.18.0__py3-none-any.whl

ansible/modules/group.py

@@ -37,7 +37,7 @@ options:
     force:
         description:
             - Whether to delete a group even if it is the primary group of a user.
-            - Only applicable on platforms which implement a --force flag on the group deletion command.
+            - Only applicable on platforms which implement a C(--force) flag on the group deletion command.
         type: bool
         default: false
         version_added: "2.15"
@@ -62,6 +62,22 @@ options:
         type: bool
         default: no
         version_added: "2.8"
+    gid_min:
+        description:
+            - Sets the GID_MIN value for group creation.
+            - Overwrites /etc/login.defs default value.
+            - Currently supported on Linux. Does nothing when used with other platforms.
+            - Requires O(local) is omitted or V(False).
+        type: int
+        version_added: "2.18"
+    gid_max:
+        description:
+            - Sets the GID_MAX value for group creation.
+            - Overwrites /etc/login.defs default value.
+            - Currently supported on Linux. Does nothing when used with other platforms.
+            - Requires O(local) is omitted or V(False).
+        type: int
+        version_added: "2.18"
 extends_documentation_fragment: action_common_attributes
 attributes:
     check_mode:
@@ -151,6 +167,14 @@ class Group(object):
         self.system = module.params['system']
         self.local = module.params['local']
         self.non_unique = module.params['non_unique']
+        self.gid_min = module.params['gid_min']
+        self.gid_max = module.params['gid_max']
+
+        if self.local:
+            if self.gid_min is not None:
+                module.fail_json(msg="'gid_min' can not be used with 'local'")
+            if self.gid_max is not None:
+                module.fail_json(msg="'gid_max' can not be used with 'local'")
 
     def execute_command(self, cmd):
         return self.module.run_command(cmd)
@@ -184,6 +208,12 @@ class Group(object):
                     cmd.append('-o')
             elif key == 'system' and kwargs[key] is True:
                 cmd.append('-r')
+        if self.gid_min is not None:
+            cmd.append('-K')
+            cmd.append('GID_MIN=' + str(self.gid_min))
+        if self.gid_max is not None:
+            cmd.append('-K')
+            cmd.append('GID_MAX=' + str(self.gid_max))
         cmd.append(self.name)
         return self.execute_command(cmd)
 
@@ -292,6 +322,12 @@ class SunOS(Group):
                 cmd.append(str(kwargs[key]))
                 if self.non_unique:
                     cmd.append('-o')
+        if self.gid_min is not None:
+            cmd.append('-K')
+            cmd.append('GID_MIN=' + str(self.gid_min))
+        if self.gid_max is not None:
+            cmd.append('-K')
+            cmd.append('GID_MAX=' + str(self.gid_max))
         cmd.append(self.name)
         return self.execute_command(cmd)
 
@@ -323,6 +359,12 @@ class AIX(Group):
                 cmd.append('id=' + str(kwargs[key]))
             elif key == 'system' and kwargs[key] is True:
                 cmd.append('-a')
+        if self.gid_min is not None:
+            cmd.append('-K')
+            cmd.append('GID_MIN=' + str(self.gid_min))
+        if self.gid_max is not None:
+            cmd.append('-K')
+            cmd.append('GID_MAX=' + str(self.gid_max))
         cmd.append(self.name)
         return self.execute_command(cmd)
 
@@ -368,6 +410,12 @@ class FreeBsdGroup(Group):
             cmd.append(str(self.gid))
             if self.non_unique:
                 cmd.append('-o')
+        if self.gid_min is not None:
+            cmd.append('-K')
+            cmd.append('GID_MIN=' + str(self.gid_min))
+        if self.gid_max is not None:
+            cmd.append('-K')
+            cmd.append('GID_MAX=' + str(self.gid_max))
         return self.execute_command(cmd)
 
     def group_mod(self, **kwargs):
@@ -492,6 +540,12 @@ class OpenBsdGroup(Group):
             cmd.append(str(self.gid))
             if self.non_unique:
                 cmd.append('-o')
+        if self.gid_min is not None:
+            cmd.append('-K')
+            cmd.append('GID_MIN=' + str(self.gid_min))
+        if self.gid_max is not None:
+            cmd.append('-K')
+            cmd.append('GID_MAX=' + str(self.gid_max))
         cmd.append(self.name)
         return self.execute_command(cmd)
 
@@ -538,6 +592,12 @@ class NetBsdGroup(Group):
             cmd.append(str(self.gid))
             if self.non_unique:
                 cmd.append('-o')
+        if self.gid_min is not None:
+            cmd.append('-K')
+            cmd.append('GID_MIN=' + str(self.gid_min))
+        if self.gid_max is not None:
+            cmd.append('-K')
+            cmd.append('GID_MAX=' + str(self.gid_max))
         cmd.append(self.name)
         return self.execute_command(cmd)
 
@@ -578,6 +638,14 @@ class BusyBoxGroup(Group):
         if self.system:
             cmd.append('-S')
 
+        if self.gid_min is not None:
+            cmd.append('-K')
+            cmd.append('GID_MIN=' + str(self.gid_min))
+
+        if self.gid_max is not None:
+            cmd.append('-K')
+            cmd.append('GID_MAX=' + str(self.gid_max))
+
         cmd.append(self.name)
 
         return self.execute_command(cmd)
@@ -626,6 +694,8 @@ def main():
             system=dict(type='bool', default=False),
             local=dict(type='bool', default=False),
             non_unique=dict(type='bool', default=False),
+            gid_min=dict(type='int'),
+            gid_max=dict(type='int'),
         ),
         supports_check_mode=True,
         required_if=[

ansible/modules/hostname.py

@@ -36,7 +36,7 @@ options:
         description:
             - Which strategy to use to update the hostname.
             - If not set we try to autodetect, but this can be problematic, particularly with containers as they can present misleading information.
-            - Note that 'systemd' should be specified for RHEL/EL/CentOS 7+. Older distributions should use 'redhat'.
+            - Note that V(systemd) should be specified for RHEL/EL/CentOS 7+. Older distributions should use V(redhat).
         choices: ['alpine', 'debian', 'freebsd', 'generic', 'macos', 'macosx', 'darwin', 'openbsd', 'openrc', 'redhat', 'sles', 'solaris', 'systemd']
         type: str
         version_added: '2.9'
@@ -516,7 +516,7 @@ class DarwinStrategy(BaseStrategy):
     However, macOS also has LocalHostName and ComputerName settings.
     LocalHostName controls the Bonjour/ZeroConf name, used by services
     like AirDrop. This class implements a method, _scrub_hostname(), that mimics
-    the transformations macOS makes on hostnames when enterened in the Sharing
+    the transformations macOS makes on hostnames when entered in the Sharing
     preference pane. It replaces spaces with dashes and removes all special
     characters.
 
@@ -886,8 +886,6 @@ def main():
 
     if name != current_hostname:
         name_before = current_hostname
-    elif name != permanent_hostname:
-        name_before = permanent_hostname
     else:
         name_before = permanent_hostname
 

ansible/modules/include_vars.py

@@ -21,20 +21,20 @@ options:
   file:
     description:
       - The file name from which variables should be loaded.
-      - If the path is relative, it will look for the file in vars/ subdirectory of a role or relative to playbook.
+      - If the path is relative, it will look for the file in C(vars/) subdirectory of a role or relative to playbook.
     type: path
     version_added: "2.2"
   dir:
     description:
       - The directory name from which the variables should be loaded.
-      - If the path is relative and the task is inside a role, it will look inside the role's vars/ subdirectory.
+      - If the path is relative and the task is inside a role, it will look inside the role's C(vars/) subdirectory.
       - If the path is relative and not inside a role, it will be parsed relative to the playbook.
     type: path
     version_added: "2.2"
   name:
     description:
       - The name of a variable into which assign the included vars.
-      - If omitted (null) they will be made top level vars.
+      - If omitted (V(null)) they will be made top level vars.
     type: str
     version_added: "2.2"
   depth:
@@ -81,8 +81,8 @@ options:
     version_added: "2.12"
   free-form:
     description:
-      - This module allows you to specify the 'file' option directly without any other options.
-      - There is no 'free-form' option, this is just an indicator, see example below.
+      - This module allows you to specify the O(file) option directly without any other options.
+      - There is no O(ignore:free-form) option, this is just an indicator, see example below.
 extends_documentation_fragment:
     - action_common_attributes
     - action_common_attributes.conn

ansible/modules/iptables.py

@@ -39,7 +39,7 @@ options:
     description:
       - This option specifies the packet matching table on which the command should operate.
       - If the kernel is configured with automatic module loading, an attempt will be made
-         to load the appropriate module for that table if it is not already there.
+        to load the appropriate module for that table if it is not already there.
     type: str
     choices: [ filter, nat, mangle, raw, security ]
     default: filter
@@ -135,7 +135,7 @@ options:
         a specific property.
       - The set of matches makes up the condition under which a target is invoked.
       - Matches are evaluated first to last if specified as an array and work in short-circuit
-        fashion, i.e. if one extension yields false, the evaluation will stop.
+        fashion, in other words if one extension yields false, the evaluation will stop.
     type: list
     elements: str
     default: []
@@ -153,7 +153,7 @@ options:
   gateway:
     description:
       - This specifies the IP address of the host to send the cloned packets.
-      - This option is only valid when O(jump) is set to V(TEE).
+      - This option is only valid when O(jump=TEE).
     type: str
     version_added: "2.8"
   log_prefix:
@@ -165,7 +165,7 @@ options:
     description:
       - Logging level according to the syslogd-defined priorities.
       - The value can be strings or numbers from 1-8.
-      - This parameter is only applicable if O(jump) is set to V(LOG).
+      - This parameter is only applicable if O(jump=LOG).
     type: str
     version_added: "2.8"
     choices: [ '0', '1', '2', '3', '4', '5', '6', '7', 'emerg', 'alert', 'crit', 'error', 'warning', 'notice', 'info', 'debug' ]
@@ -242,13 +242,13 @@ options:
     type: str
   to_destination:
     description:
-      - This specifies a destination address to use with C(DNAT).
+      - This specifies a destination address to use with O(ctstate=DNAT).
       - Without this, the destination address is never altered.
     type: str
     version_added: "2.1"
   to_source:
     description:
-      - This specifies a source address to use with C(SNAT).
+      - This specifies a source address to use with O(ctstate=SNAT).
       - Without this, the source address is never altered.
     type: str
     version_added: "2.2"
@@ -342,14 +342,14 @@ options:
   reject_with:
     description:
       - 'Specifies the error packet type to return while rejecting. It implies
-        "jump: REJECT".'
+        C(jump=REJECT).'
     type: str
     version_added: "2.1"
   icmp_type:
     description:
       - This allows specification of the ICMP type, which can be a numeric
         ICMP type, type/code pair, or one of the ICMP type names shown by the
-        command 'iptables -p icmp -h'
+        command C(iptables -p icmp -h).
     type: str
     version_added: "2.2"
   flush:
@@ -387,10 +387,10 @@ options:
     version_added: "2.13"
   numeric:
     description:
-      - This parameter controls the running of the list -action of iptables, which is used internally by the module
-      - Does not affect the actual functionality. Use this if iptables hang when creating a chain or altering policy
-      - If V(true), then iptables skips the DNS-lookup of the IP addresses in a chain when it uses the list -action
-      - Listing is used internally for example when setting a policy or creating a chain
+      - This parameter controls the running of the list -action of iptables, which is used internally by the module.
+      - Does not affect the actual functionality. Use this if iptables hang when creating a chain or altering policy.
+      - If V(true), then iptables skips the DNS-lookup of the IP addresses in a chain when it uses the list -action.
+      - Listing is used internally for example when setting a policy or creating a chain.
     type: bool
     default: false
     version_added: "2.15"
@@ -848,6 +848,7 @@ def main():
         required_if=[
             ['jump', 'TEE', ['gateway']],
             ['jump', 'tee', ['gateway']],
+            ['flush', False, ['chain']],
         ]
     )
     args = dict(
@@ -865,10 +866,6 @@ def main():
     ip_version = module.params['ip_version']
     iptables_path = module.get_bin_path(BINS[ip_version], True)
 
-    # Check if chain option is required
-    if args['flush'] is False and args['chain'] is None:
-        module.fail_json(msg="Either chain or flush parameter must be specified.")
-
     if module.params.get('log_prefix', None) or module.params.get('log_level', None):
         if module.params['jump'] is None:
             module.params['jump'] = 'LOG'

ansible/modules/known_hosts.py

@@ -10,7 +10,7 @@ DOCUMENTATION = r'''
 module: known_hosts
 short_description: Add or remove a host from the C(known_hosts) file
 description:
-   - The M(ansible.builtin.known_hosts) module lets you add or remove a host keys from the C(known_hosts) file.
+   - The M(ansible.builtin.known_hosts) module lets you add or remove host keys from the C(known_hosts) file.
    - Starting at Ansible 2.2, multiple entries per host are allowed, but only one for each key type supported by ssh.
      This is useful if you're going to want to use the M(ansible.builtin.git) module over ssh, for example.
    - If you have a very large number of host keys to manage, you will find the M(ansible.builtin.template) module more useful.
@@ -19,7 +19,7 @@ options:
   name:
     aliases: [ 'host' ]
     description:
-      - The host to add or remove (must match a host specified in key). It will be converted to lowercase so that ssh-keygen can find it.
+      - The host to add or remove (must match a host specified in key). It will be converted to lowercase so that C(ssh-keygen) can find it.
       - Must match with <hostname> or <ip> present in key attribute.
       - For custom SSH port, O(name) needs to specify port as well. See example section.
     type: str
@@ -49,8 +49,8 @@ options:
     version_added: "2.3"
   state:
     description:
-      - V(present) to add the host key.
-      - V(absent) to remove it.
+      - V(present) to add host keys.
+      - V(absent) to remove host keys.
     choices: [ "absent", "present" ]
     default: "present"
     type: str
@@ -101,6 +101,7 @@ EXAMPLES = r'''
 #    state = absent|present (default: present)
 
 import base64
+import copy
 import errno
 import hashlib
 import hmac
@@ -118,6 +119,7 @@ def enforce_state(module, params):
     Add or remove key.
     """
 
+    results = dict(changed=False)
     host = params["name"].lower()
     key = params.get("key", None)
     path = params.get("path")
@@ -140,13 +142,12 @@ def enforce_state(module, params):
 
     found, replace_or_add, found_line = search_for_host_key(module, host, key, path, sshkeygen)
 
-    params['diff'] = compute_diff(path, found_line, replace_or_add, state, key)
+    results['diff'] = compute_diff(path, found_line, replace_or_add, state, key)
 
     # check if we are trying to remove a non matching key,
     # in that case return with no change to the host
     if state == 'absent' and not found_line and key:
-        params['changed'] = False
-        return params
+        return results
 
     # We will change state if found==True & state!="present"
     # or found==False & state=="present"
@@ -154,15 +155,15 @@ def enforce_state(module, params):
     # Alternatively, if replace is true (i.e. key present, and we must change
     # it)
     if module.check_mode:
-        module.exit_json(changed=replace_or_add or (state == "present") != found,
-                         diff=params['diff'])
+        results['changed'] = replace_or_add or (state == "present") != found
+        module.exit_json(**results)
 
     # Now do the work.
 
     # Only remove whole host if found and no key provided
     if found and not key and state == "absent":
         module.run_command([sshkeygen, '-R', host, '-f', path], check_rc=True)
-        params['changed'] = True
+        results['changed'] = True
 
     # Next, add a new (or replacing) entry
     if replace_or_add or found != (state == "present"):
@@ -188,9 +189,9 @@ def enforce_state(module, params):
         else:
             module.atomic_move(outf.name, path)
 
-        params['changed'] = True
+        results['changed'] = True
 
-    return params
+    return results
 
 
 def sanity_check(module, host, key, sshkeygen):
@@ -364,7 +365,9 @@ def main():
         supports_check_mode=True
     )
 
-    results = enforce_state(module, module.params)
+    # TODO: deprecate returning everything that was passed in
+    results = copy.copy(module.params)
+    results.update(enforce_state(module, module.params))
     module.exit_json(**results)
 
 

ansible/modules/lineinfile.py

@@ -87,13 +87,11 @@ options:
       - If specified, the line will be inserted after the last match of specified regular expression.
       - If the first match is required, use(firstmatch=yes).
       - A special value is available; V(EOF) for inserting the line at the end of the file.
-      - If specified regular expression has no matches, EOF will be used instead.
+      - If specified regular expression has no matches or no value is passed, V(EOF) will be used instead.
       - If O(insertbefore) is set, default value V(EOF) will be ignored.
       - If regular expressions are passed to both O(regexp) and O(insertafter), O(insertafter) is only honored if no match for O(regexp) is found.
       - May not be used with O(backrefs) or O(insertbefore).
     type: str
-    choices: [ EOF, '*regex*' ]
-    default: EOF
   insertbefore:
     description:
       - Used with O(state=present).
@@ -104,7 +102,6 @@ options:
       - If regular expressions are passed to both O(regexp) and O(insertbefore), O(insertbefore) is only honored if no match for O(regexp) is found.
       - May not be used with O(backrefs) or O(insertafter).
     type: str
-    choices: [ BOF, '*regex*' ]
     version_added: "1.1"
   create:
     description:

ansible/modules/meta.py

@@ -33,7 +33,12 @@ options:
         - V(end_host) (added in Ansible 2.8) is a per-host variation of V(end_play). Causes the play to end for the current host without failing it.
         - V(end_batch) (added in Ansible 2.12) causes the current batch (see C(serial)) to end without failing the host(s).
           Note that with C(serial=0) or undefined this behaves the same as V(end_play).
-    choices: [ clear_facts, clear_host_errors, end_host, end_play, flush_handlers, noop, refresh_inventory, reset_connection, end_batch ]
+        - V(end_role) (added in Ansible 2.18) causes the currently executing role to end without failing the host(s).
+          Effectively all tasks from within a role after V(end_role) is executed are ignored. Since handlers live in a global,
+          play scope, all handlers added via the role are unaffected and are still executed if notified. It is an error
+          to call V(end_role) from outside of a role or from a handler. Note that V(end_role) does not have an effect to
+          the parent roles or roles that depend (via dependencies in meta/main.yml) on a role executing V(end_role).
+    choices: [ clear_facts, clear_host_errors, end_host, end_play, flush_handlers, noop, refresh_inventory, reset_connection, end_batch, end_role ]
     required: true
 extends_documentation_fragment:
     - action_common_attributes