user - add parameter for password expiration warning days (#79884)

* user - add parameter to set number of warning days before password expires

Signed-off-by: Norman Ziegner <norman.ziegner@ufz.de>

changelogs/fragments/user-add-password-exp-warning.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - user - add new option ``password_expire_warn`` (supported on Linux only) to set the number of days of warning before a password change is required (https://github.com/ansible/ansible/issues/79882).

lib/ansible/modules/user.py

@@ -254,6 +254,12 @@ 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.
@@ -340,6 +346,11 @@ 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'''
@@ -564,6 +575,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:
@@ -1080,6 +1092,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:
@@ -1089,8 +1102,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'
@@ -1099,6 +1113,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)
@@ -3092,6 +3108,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

test/integration/targets/user/tasks/main.yml

@@ -32,6 +32,7 @@
 - import_tasks: test_expires_new_account.yml
 - import_tasks: test_expires_new_account_epoch_negative.yml
 - import_tasks: test_expires_min_max.yml
+- import_tasks: test_expires_warn.yml
 - import_tasks: test_shadow_backup.yml
 - import_tasks: test_ssh_key_passphrase.yml
 - import_tasks: test_password_lock.yml

test/integration/targets/user/tasks/test_expires_warn.yml

@@ -0,0 +1,36 @@
+# https://github.com/ansible/ansible/issues/79882
+- name: Test setting warning days
+  when: ansible_facts.os_family in ['RedHat', 'Debian', 'Suse']
+  block:
+    - name: create user
+      user:
+        name: ansibulluser
+        state: present
+
+    - name: add warning days for password
+      user:
+        name: ansibulluser
+        password_expire_warn: 28
+      register: pass_warn_1_0
+
+    - name: again add warning days for password
+      user:
+        name: ansibulluser
+        password_expire_warn: 28
+      register: pass_warn_1_1
+
+    - name: validate result for warning days
+      assert:
+        that:
+          - pass_warn_1_0 is changed
+          - pass_warn_1_1 is not changed
+
+    - name: Get shadow data for ansibulluser
+      getent:
+        database: shadow
+        key: ansibulluser
+
+    - name: Ensure number of warning days was set properly
+      assert:
+        that:
+          - ansible_facts.getent_shadow['ansibulluser'][4] == '28'