Adding upstream version 2.16.5.upstream/2.16.5

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 99 insertions, 75 deletions

diff --git a/lib/ansible/modules/user.py b/lib/ansible/modules/user.py
index 2fc4e47..6d465b0 100644
--- a/lib/ansible/modules/user.py
+++ b/lib/ansible/modules/user.py
@@ -28,11 +28,12 @@ options:
     comment:
         description:
             - Optionally sets the description (aka I(GECOS)) of user account.
+            - On macOS, this defaults to the O(name) option.
         type: str
     hidden:
         description:
             - macOS only, optionally hide the user from the login window and system preferences.
-            - The default will be C(true) if the I(system) option is used.
+            - The default will be V(true) if the O(system) option is used.
         type: bool
         version_added: "2.6"
     non_unique:
@@ -49,28 +50,29 @@ options:
     group:
         description:
             - Optionally sets the user's primary group (takes a group name).
+            - On macOS, this defaults to V('staff')
         type: str
     groups:
         description:
-            - List of groups user will be added to.
-            - By default, the user is removed from all other groups. Configure C(append) to modify this.
-            - When set to an empty string C(''),
+            - A list of supplementary groups which the user is also a member of.
+            - By default, the user is removed from all other groups. Configure O(append) to modify this.
+            - When set to an empty string V(''),
               the user is removed from all groups except the primary group.
             - Before Ansible 2.3, the only input format allowed was a comma separated string.
         type: list
         elements: str
     append:
         description:
-            - If C(true), add the user to the groups specified in C(groups).
-            - If C(false), user will only be added to the groups specified in C(groups),
+            - If V(true), add the user to the groups specified in O(groups).
+            - If V(false), user will only be added to the groups specified in O(groups),
               removing them from all other groups.
         type: bool
         default: no
     shell:
         description:
             - Optionally set the user's shell.
-            - On macOS, before Ansible 2.5, the default shell for non-system users was C(/usr/bin/false).
-              Since Ansible 2.5, the default shell for non-system users on macOS is C(/bin/bash).
+            - On macOS, before Ansible 2.5, the default shell for non-system users was V(/usr/bin/false).
+              Since Ansible 2.5, the default shell for non-system users on macOS is V(/bin/bash).
             - See notes for details on how other operating systems determine the default shell by
               the underlying tool.
         type: str
@@ -81,7 +83,7 @@ options:
     skeleton:
         description:
             - Optionally set a home skeleton directory.
-            - Requires C(create_home) option!
+            - Requires O(create_home) option!
         type: str
         version_added: "2.0"
     password:
@@ -90,46 +92,51 @@ options:
             - B(Linux/Unix/POSIX:) Enter the hashed password as the value.
             - See L(FAQ entry,https://docs.ansible.com/ansible/latest/reference_appendices/faq.html#how-do-i-generate-encrypted-passwords-for-the-user-module)
               for details on various ways to generate the hash of a password.
-            - To create an account with a locked/disabled password on Linux systems, set this to C('!') or C('*').
-            - To create an account with a locked/disabled password on OpenBSD, set this to C('*************').
+            - To create an account with a locked/disabled password on Linux systems, set this to V('!') or V('*').
+            - To create an account with a locked/disabled password on OpenBSD, set this to V('*************').
             - B(OS X/macOS:) Enter the cleartext password as the value. Be sure to take relevant security precautions.
+            - On macOS, the password specified in the C(password) option will always be set, regardless of whether the user account already exists or not.
+            - When the password is passed as an argument, the C(user) module will always return changed to C(true) for macOS systems.
+              Since macOS no longer provides access to the hashed passwords directly.
         type: str
     state:
         description:
             - Whether the account should exist or not, taking action if the state is different from what is stated.
+            - See this L(FAQ entry,https://docs.ansible.com/ansible/latest/reference_appendices/faq.html#running-on-macos-as-a-target)
+              for additional requirements when removing users on macOS systems.
         type: str
         choices: [ absent, present ]
         default: present
     create_home:
         description:
-            - Unless set to C(false), a home directory will be made for the user
+            - Unless set to V(false), a home directory will be made for the user
               when the account is created or if the home directory does not exist.
-            - Changed from C(createhome) to C(create_home) in Ansible 2.5.
+            - Changed from O(createhome) to O(create_home) in Ansible 2.5.
         type: bool
         default: yes
         aliases: [ createhome ]
     move_home:
         description:
-            - "If set to C(true) when used with C(home: ), attempt to move the user's old home
+            - "If set to V(true) when used with O(home), attempt to move the user's old home
               directory to the specified directory if it isn't there already and the old home exists."
         type: bool
         default: no
     system:
         description:
-            - When creating an account C(state=present), setting this to C(true) makes the user a system account.
+            - When creating an account O(state=present), setting this to V(true) makes the user a system account.
             - This setting cannot be changed on existing users.
         type: bool
         default: no
     force:
         description:
-            - This only affects C(state=absent), it forces removal of the user and associated directories on supported platforms.
+            - This only affects O(state=absent), it forces removal of the user and associated directories on supported platforms.
             - The behavior is the same as C(userdel --force), check the man page for C(userdel) on your system for details and support.
-            - When used with C(generate_ssh_key=yes) this forces an existing key to be overwritten.
+            - When used with O(generate_ssh_key=yes) this forces an existing key to be overwritten.
         type: bool
         default: no
     remove:
         description:
-            - This only affects C(state=absent), it attempts to remove directories associated with the user.
+            - This only affects O(state=absent), it attempts to remove directories associated with the user.
             - The behavior is the same as C(userdel --remove), check the man page for details and support.
         type: bool
         default: no
@@ -140,7 +147,7 @@ options:
     generate_ssh_key:
         description:
             - Whether to generate a SSH key for the user in question.
-            - This will B(not) overwrite an existing SSH key unless used with C(force=yes).
+            - This will B(not) overwrite an existing SSH key unless used with O(force=yes).
         type: bool
         default: no
         version_added: "0.9"
@@ -162,7 +169,7 @@ options:
         description:
             - Optionally specify the SSH key filename.
             - If this is a relative filename then it will be relative to the user's home directory.
-            - This parameter defaults to I(.ssh/id_rsa).
+            - This parameter defaults to V(.ssh/id_rsa).
         type: path
         version_added: "0.9"
     ssh_key_comment:
@@ -179,8 +186,8 @@ options:
         version_added: "0.9"
     update_password:
         description:
-            - C(always) will update passwords if they differ.
-            - C(on_create) will only set the password for newly created users.
+            - V(always) will update passwords if they differ.
+            - V(on_create) will only set the password for newly created users.
         type: str
         choices: [ always, on_create ]
         default: always
@@ -198,7 +205,7 @@ options:
             - Lock the password (C(usermod -L), C(usermod -U), C(pw lock)).
             - Implementation differs by platform. This option does not always mean the user cannot login using other methods.
             - This option does not disable the user, only lock the password.
-            - This must be set to C(False) in order to unlock a currently locked password. The absence of this parameter will not unlock a password.
+            - This must be set to V(False) in order to unlock a currently locked password. The absence of this parameter will not unlock a password.
             - Currently supported on Linux, FreeBSD, DragonFlyBSD, NetBSD, OpenBSD.
         type: bool
         version_added: "2.6"
@@ -216,28 +223,25 @@ options:
     profile:
         description:
             - Sets the profile of the user.
-            - Does nothing when used with other platforms.
             - Can set multiple profiles using comma separation.
-            - To delete all the profiles, use C(profile='').
-            - Currently supported on Illumos/Solaris.
+            - To delete all the profiles, use O(profile='').
+            - Currently supported on Illumos/Solaris. Does nothing when used with other platforms.
         type: str
         version_added: "2.8"
     authorization:
         description:
             - Sets the authorization of the user.
-            - Does nothing when used with other platforms.
             - Can set multiple authorizations using comma separation.
-            - To delete all authorizations, use C(authorization='').
-            - Currently supported on Illumos/Solaris.
+            - To delete all authorizations, use O(authorization='').
+            - Currently supported on Illumos/Solaris. Does nothing when used with other platforms.
         type: str
         version_added: "2.8"
     role:
         description:
             - Sets the role of the user.
-            - Does nothing when used with other platforms.
             - Can set multiple roles using comma separation.
-            - To delete all roles, use C(role='').
-            - Currently supported on Illumos/Solaris.
+            - To delete all roles, use O(role='').
+            - Currently supported on Illumos/Solaris. Does nothing when used with other platforms.
         type: str
         version_added: "2.8"
     password_expire_max:
@@ -252,12 +256,17 @@ options:
             - Supported on Linux only.
         type: int
         version_added: "2.11"
+    password_expire_warn:
+        description:
+            - Number of days of warning before password expires.
+            - Supported on Linux only.
+        type: int
+        version_added: "2.16"
     umask:
         description:
             - Sets the umask of the user.
-            - Does nothing when used with other platforms.
-            - Currently supported on Linux.
-            - Requires C(local) is omitted or False.
+            - Currently supported on Linux. Does nothing when used with other platforms.
+            - Requires O(local) is omitted or V(False).
         type: str
         version_added: "2.12"
 extends_documentation_fragment: action_common_attributes
@@ -338,12 +347,17 @@ EXAMPLES = r'''
   ansible.builtin.user:
     name: pushkar15
     password_expire_min: 5
+
+- name: Set number of warning days for password expiration
+  ansible.builtin.user:
+    name: jane157
+    password_expire_warn: 30
 '''
 
 RETURN = r'''
 append:
   description: Whether or not to append the user to groups.
-  returned: When state is C(present) and the user exists
+  returned: When O(state) is V(present) and the user exists
   type: bool
   sample: True
 comment:
@@ -358,7 +372,7 @@ create_home:
   sample: True
 force:
   description: Whether or not a user account was forcibly deleted.
-  returned: When I(state) is C(absent) and user exists
+  returned: When O(state) is V(absent) and user exists
   type: bool
   sample: False
 group:
@@ -368,17 +382,17 @@ group:
   sample: 1001
 groups:
   description: List of groups of which the user is a member.
-  returned: When I(groups) is not empty and I(state) is C(present)
+  returned: When O(groups) is not empty and O(state) is V(present)
   type: str
   sample: 'chrony,apache'
 home:
   description: "Path to user's home directory."
-  returned: When I(state) is C(present)
+  returned: When O(state) is V(present)
   type: str
   sample: '/home/asmith'
 move_home:
   description: Whether or not to move an existing home directory.
-  returned: When I(state) is C(present) and user exists
+  returned: When O(state) is V(present) and user exists
   type: bool
   sample: False
 name:
@@ -388,32 +402,32 @@ name:
   sample: asmith
 password:
   description: Masked value of the password.
-  returned: When I(state) is C(present) and I(password) is not empty
+  returned: When O(state) is V(present) and O(password) is not empty
   type: str
   sample: 'NOT_LOGGING_PASSWORD'
 remove:
   description: Whether or not to remove the user account.
-  returned: When I(state) is C(absent) and user exists
+  returned: When O(state) is V(absent) and user exists
   type: bool
   sample: True
 shell:
   description: User login shell.
-  returned: When I(state) is C(present)
+  returned: When O(state) is V(present)
   type: str
   sample: '/bin/bash'
 ssh_fingerprint:
   description: Fingerprint of generated SSH key.
-  returned: When I(generate_ssh_key) is C(True)
+  returned: When O(generate_ssh_key) is V(True)
   type: str
   sample: '2048 SHA256:aYNHYcyVm87Igh0IMEDMbvW0QDlRQfE0aJugp684ko8 ansible-generated on host (RSA)'
 ssh_key_file:
   description: Path to generated SSH private key file.
-  returned: When I(generate_ssh_key) is C(True)
+  returned: When O(generate_ssh_key) is V(True)
   type: str
   sample: /home/asmith/.ssh/id_rsa
 ssh_public_key:
   description: Generated SSH public key file.
-  returned: When I(generate_ssh_key) is C(True)
+  returned: When O(generate_ssh_key) is V(True)
   type: str
   sample: >
     'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC95opt4SPEC06tOYsJQJIuN23BbLMGmYo8ysVZQc4h2DZE9ugbjWWGS1/pweUGjVstgzMkBEeBCByaEf/RJKNecKRPeGd2Bw9DCj/bn5Z6rGfNENKBmo
@@ -431,30 +445,18 @@ stdout:
   sample:
 system:
   description: Whether or not the account is a system account.
-  returned: When I(system) is passed to the module and the account does not exist
+  returned: When O(system) is passed to the module and the account does not exist
   type: bool
   sample: True
 uid:
   description: User ID of the user account.
-  returned: When I(uid) is passed to the module
+  returned: When O(uid) is passed to the module
   type: int
   sample: 1044
-password_expire_max:
-  description: Maximum number of days during which a password is valid.
-  returned: When user exists
-  type: int
-  sample: 20
-password_expire_min:
-  description: Minimum number of days between password change
-  returned: When user exists
-  type: int
-  sample: 20
 '''
 
 
-import ctypes
 import ctypes.util
-import errno
 import grp
 import calendar
 import os
@@ -469,7 +471,7 @@ import time
 import math
 
 from ansible.module_utils import distro
-from ansible.module_utils._text import to_bytes, to_native, to_text
+from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.common.locale import get_best_parsable_locale
 from ansible.module_utils.common.sys_info import get_platform_subclass
@@ -574,6 +576,7 @@ class User(object):
         self.role = module.params['role']
         self.password_expire_max = module.params['password_expire_max']
         self.password_expire_min = module.params['password_expire_min']
+        self.password_expire_warn = module.params['password_expire_warn']
         self.umask = module.params['umask']
 
         if self.umask is not None and self.local:
@@ -867,7 +870,7 @@ class User(object):
                 if current_groups and not self.append:
                     groups_need_mod = True
             else:
-                groups = self.get_groups_set(remove_existing=False)
+                groups = self.get_groups_set(remove_existing=False, names_only=True)
                 group_diff = set(current_groups).symmetric_difference(groups)
 
                 if group_diff:
@@ -913,7 +916,8 @@ class User(object):
 
         if self.expires is not None:
 
-            current_expires = int(self.user_password()[1])
+            current_expires = self.user_password()[1] or '0'
+            current_expires = int(current_expires)
 
             if self.expires < time.gmtime(0):
                 if current_expires >= 0:
@@ -1008,16 +1012,22 @@ class User(object):
         except (ValueError, KeyError):
             return list(grp.getgrnam(group))
 
-    def get_groups_set(self, remove_existing=True):
+    def get_groups_set(self, remove_existing=True, names_only=False):
         if self.groups is None:
             return None
         info = self.user_info()
         groups = set(x.strip() for x in self.groups.split(',') if x)
+        group_names = set()
         for g in groups.copy():
             if not self.group_exists(g):
                 self.module.fail_json(msg="Group %s does not exist" % (g))
-            if info and remove_existing and self.group_info(g)[2] == info[3]:
+            group_info = self.group_info(g)
+            if info and remove_existing and group_info[2] == info[3]:
                 groups.remove(g)
+            elif names_only:
+                group_names.add(group_info[0])
+        if names_only:
+            return group_names
         return groups
 
     def user_group_membership(self, exclude_primary=True):
@@ -1084,6 +1094,7 @@ class User(object):
     def set_password_expire(self):
         min_needs_change = self.password_expire_min is not None
         max_needs_change = self.password_expire_max is not None
+        warn_needs_change = self.password_expire_warn is not None
 
         if HAVE_SPWD:
             try:
@@ -1093,8 +1104,9 @@ class User(object):
 
             min_needs_change &= self.password_expire_min != shadow_info.sp_min
             max_needs_change &= self.password_expire_max != shadow_info.sp_max
+            warn_needs_change &= self.password_expire_warn != shadow_info.sp_warn
 
-        if not (min_needs_change or max_needs_change):
+        if not (min_needs_change or max_needs_change or warn_needs_change):
             return (None, '', '')  # target state already reached
 
         command_name = 'chage'
@@ -1103,6 +1115,8 @@ class User(object):
             cmd.extend(["-m", self.password_expire_min])
         if max_needs_change:
             cmd.extend(["-M", self.password_expire_max])
+        if warn_needs_change:
+            cmd.extend(["-W", self.password_expire_warn])
         cmd.append(self.name)
 
         return self.execute_command(cmd)
@@ -1277,7 +1291,7 @@ class User(object):
             else:
                 skeleton = '/etc/skel'
 
-            if os.path.exists(skeleton):
+            if os.path.exists(skeleton) and skeleton != os.devnull:
                 try:
                     shutil.copytree(skeleton, path, symlinks=True)
                 except OSError as e:
@@ -1523,7 +1537,7 @@ class FreeBsdUser(User):
 
         if self.groups is not None:
             current_groups = self.user_group_membership()
-            groups = self.get_groups_set()
+            groups = self.get_groups_set(names_only=True)
 
             group_diff = set(current_groups).symmetric_difference(groups)
             groups_need_mod = False
@@ -1546,7 +1560,8 @@ class FreeBsdUser(User):
 
         if self.expires is not None:
 
-            current_expires = int(self.user_password()[1])
+            current_expires = self.user_password()[1] or '0'
+            current_expires = int(current_expires)
 
             # If expiration is negative or zero and the current expiration is greater than zero, disable expiration.
             # In OpenBSD, setting expiration to zero disables expiration. It does not expire the account.
@@ -1717,7 +1732,7 @@ class OpenBSDUser(User):
                 if current_groups and not self.append:
                     groups_need_mod = True
             else:
-                groups = self.get_groups_set()
+                groups = self.get_groups_set(names_only=True)
                 group_diff = set(current_groups).symmetric_difference(groups)
 
                 if group_diff:
@@ -1893,7 +1908,7 @@ class NetBSDUser(User):
                 if current_groups and not self.append:
                     groups_need_mod = True
             else:
-                groups = self.get_groups_set()
+                groups = self.get_groups_set(names_only=True)
                 group_diff = set(current_groups).symmetric_difference(groups)
 
                 if group_diff:
@@ -2127,7 +2142,7 @@ class SunOS(User):
 
         if self.groups is not None:
             current_groups = self.user_group_membership()
-            groups = self.get_groups_set()
+            groups = self.get_groups_set(names_only=True)
             group_diff = set(current_groups).symmetric_difference(groups)
             groups_need_mod = False
 
@@ -2404,7 +2419,7 @@ class DarwinUser(User):
 
         current = set(self._list_user_groups())
         if self.groups is not None:
-            target = set(self.groups.split(','))
+            target = self.get_groups_set(names_only=True)
         else:
             target = set([])
 
@@ -2498,6 +2513,14 @@ class DarwinUser(User):
         if rc != 0:
             self.module.fail_json(msg='Cannot create user "%s".' % self.name, err=err, out=out, rc=rc)
 
+        # Make the Gecos (alias display name) default to username
+        if self.comment is None:
+            self.comment = self.name
+
+        # Make user group default to 'staff'
+        if self.group is None:
+            self.group = 'staff'
+
         self._make_group_numerical()
         if self.uid is None:
             self.uid = str(self._get_next_uid(self.system))
@@ -2688,7 +2711,7 @@ class AIX(User):
                 if current_groups and not self.append:
                     groups_need_mod = True
             else:
-                groups = self.get_groups_set()
+                groups = self.get_groups_set(names_only=True)
                 group_diff = set(current_groups).symmetric_difference(groups)
 
                 if group_diff:
@@ -2886,7 +2909,7 @@ class HPUX(User):
                 if current_groups and not self.append:
                     groups_need_mod = True
             else:
-                groups = self.get_groups_set(remove_existing=False)
+                groups = self.get_groups_set(remove_existing=False, names_only=True)
                 group_diff = set(current_groups).symmetric_difference(groups)
 
                 if group_diff:
@@ -3096,6 +3119,7 @@ def main():
             login_class=dict(type='str'),
             password_expire_max=dict(type='int', no_log=False),
             password_expire_min=dict(type='int', no_log=False),
+            password_expire_warn=dict(type='int', no_log=False),
             # following options are specific to macOS
             hidden=dict(type='bool'),
             # following options are specific to selinux