Skip to content

pwquality Ansible Role

An Ansible role to install and configure libpam-pwquality on Debian-based systems.

Features

  • Install and manage libpam-pwquality
  • Manage /etc/security/pwquality.conf with all upstream directives
  • Full uninstall support

Installation

Add the following to your requirements.yml:

roles:
  - name: pwquality
    src: https://gitlab.com/niclas-zone/tools/ansible/roles/pwquality.git
    version: 1.0.0
    scm: git

Then install:

ansible-galaxy install -r requirements.yml --force

Role Variables

Role behaviour

Variable Default Type Description
ansible_managed_warning "This file is managed by Ansible. Manual changes will be overwritten." string Header comment embedded in templated files
ansible_role_repository https://gitlab.com/niclas-zone/tools/ansible/roles/pwquality string Repository URL for this role
ansible_role_used_in_repository "{{ ansible_role_repository }}" string URL of the consuming repository
pwquality_state "present" string present to install and configure, absent to remove
pwquality_manage_package true boolean Whether the role installs/removes the libpam-pwquality package
pwquality_config_file "/etc/security/pwquality.conf" string Path to the configuration file
pwquality_config_file_owner "root" string Owner of the configuration file
pwquality_config_file_group "root" string Group of the configuration file
pwquality_config_file_mode "0644" string Permissions for the configuration file

pwquality.conf directives

Each variable maps directly to the corresponding pwquality.conf(5) directive. Defaults match the upstream pwquality defaults.

Variable Default Description
pwquality_difok 1 Characters in the new password that must not appear in the old password
pwquality_minlen 8 Minimum acceptable password length (cannot be set below 6)
pwquality_dcredit 0 Credit/requirement for digits (negative = minimum count)
pwquality_ucredit 0 Credit/requirement for uppercase letters (negative = minimum count)
pwquality_lcredit 0 Credit/requirement for lowercase letters (negative = minimum count)
pwquality_ocredit 0 Credit/requirement for other characters (negative = minimum count)
pwquality_minclass 0 Minimum number of required character classes
pwquality_maxrepeat 0 Maximum consecutive identical characters (0 = disabled)
pwquality_maxclassrepeat 0 Maximum consecutive characters from the same class (0 = disabled)
pwquality_gecoscheck 0 Check password against the user's GECOS field (non-zero = enabled)
pwquality_dictcheck 1 Check password against the cracklib dictionary (non-zero = enabled)
pwquality_usercheck 1 Check if password contains the username (non-zero = enabled)
pwquality_usersubstr 0 Length of username substrings to check (requires usercheck, 0 = disabled)
pwquality_enforcing 1 Reject bad passwords (1), or warn only (0)
pwquality_dictpath "" Path to cracklib dictionaries (empty = use cracklib default)
pwquality_retry 3 Number of retries before returning an error
pwquality_enforce_for_root false Enforce checks on the root password (boolean flag — present in config when true)
pwquality_local_users_only false Skip checks for users not in /etc/passwd (boolean flag)

Example Playbooks

Basic: enforce a strong password policy

---
- hosts: servers
  become: true
  roles:
    - role: pwquality
      vars:
        pwquality_minlen: 12
        pwquality_minclass: 3
        pwquality_maxrepeat: 3
        pwquality_dcredit: -1
        pwquality_ucredit: -1
        pwquality_lcredit: -1
        pwquality_difok: 5
        pwquality_enforcing: 1
        pwquality_retry: 3
        pwquality_enforce_for_root: true

Uninstall

---
- hosts: servers
  become: true
  roles:
    - role: pwquality
      vars:
        pwquality_state: absent