Custom Ansible fact for local Linux users

users.fact

#!/usr/bin/env bash
# Requires Bash v4+
# Gathers Ansible facts for local Linux users from /etc/passwd, and optionally /etc/shadow.
# Place this under /etc/ansible/facts.d/ on your remote hosts,
# and make it executable. Ansible will save user info under the 'ansible_local' fact,
# whenever a playbook gathers facts.

# You can toggle whether to also include password expiration data from /etc/shadow.
# THIS REQUIRES ROOT PRIVILEGES TO WORK, or else empty / '0' results will be returned.
gather_shadow=true

readarray -t passwd_list < <(getent passwd)
readarray -t passwd_users < <(getent passwd | cut -d: -f1)

[ -r /etc/shadow ] && file_readable="true" || file_readable="false"

let "lastitem = ${#passwd_list[@]} - 1"

if ${gather_shadow}; then

  echo "{"
  for index in "${!passwd_list[@]}"; do
    
    # Parse the standard passwd data
    IFS=: read -r user pass uid gid description homedir shell <<< "${passwd_list[$index]}"
    # If user is not found in shadow DB, or if we don't have permissions to read, we return empty data.
    shadow_data=$(getent shadow "${user}" || echo '::::::::')
    IFS=: read -r shadowuser pwhash lastchg minage maxage warn inactive expires misc <<< "${shadow_data}"
    # 'present' is our clue to the user that we couldn't fetch the data from shadow, whatever the reason.
    [ -n "${shadowuser}" ] && present="true" || present="false"
    # Last element in the list should skip the comma at the end
    [ ${index} -eq ${lastitem} ] && delim='' || delim=','
    
    # Don't mess with the heredoc EOF spacing or Bash will cry
    cat << EOF
    "${user}": {
      "name": "${user}",
      "uid": ${uid},
      "gid": ${gid},
      "description": "${description}",
      "home": "${homedir}",
      "shell": "${shell}",
      "shadow": {
        "db_readable": ${file_readable},
        "user_found": ${present},
        "last_change": ${lastchg:-0},
        "min_age": ${minage:-0},
        "max_age": ${maxage:-0},
        "warn": ${warn:-0},
        "inactive": ${inactive:-0},
        "expires": ${expires:-0}
      }
    }${delim}
EOF
  done
  echo "}"

else

  echo "{"
  for index in "${!passwd_list[@]}"; do
    IFS=: read -r user pass uid gid description homedir shell <<< "${passwd_list[$index]}"
    [ ${index} -eq ${lastitem} ] && delim='' || delim=','
    # Don't mess with the heredoc EOF spacing or Bash will cry
    cat << EOF
    "${user}": {
      "name": "${user}",
      "uid": ${uid},
      "gid": ${gid},
      "description": "${description}",
      "home": "${homedir}",
      "shell": "${shell}"
    }${delim}
EOF
  done
  echo "}"

fi

This is an example of a custom/local Ansible fact for local Linux users on a node. It can optionally gather password expiration info from /etc/shadow, assuming the connecting user has the proper permissions.

Requirements:

• Bash v4+
• Tested on RHEL 7/8, Ubuntu 20.04

Usage:

1. Find the gather_shadow variable at the top of the script, and decide whether to toggle it true or false
2. Create folder /etc/ansible/facts.d/ on all of your remote Linux nodes, and copy the file in as users.fact
3. Make the file executable with: chmod +x /etc/ansible/facts.d/users.fact
4. To test from the remote node: log into the node with the same credentials Ansible uses, and execute the file like any bash script
5. To test from your Ansible controller, run the following command (including the comma): ansible -i your_host, -m setup your_host
6. You should see the facts populate under ansible_local.users for the node.

Gathering additional data on password expiration (gather_shadow):

• There is a variable called gather_shadow in the script, which allows you to gather extended info about password expiration for each user. However, Ansible must connect to the node with root/sudo privileges in order for this data to be accessible.
• Within the 'shadow' hash, there are two additional variables for auditing and troubleshooting:
  • db_readable: This tells you whether the script had permissions to read the /etc/shadow file. If false, then none of the shadow data for this host will be valid.
  • user_found: This will be true if results were found for a user when the shadow DB was queried. If false, then either the shadow DB was not accessible, or the user is missing an entry in the shadow DB (perhaps a defunct or stale user).

With gather_shadow=true, a user entry should look like this:

"root": {
   "name": "root",
   "uid": 0,
   "gid": 0,
   "description": "root",
   "home": "/root",
   "shell": "/bin/bash",
   "shadow": {
       "db_readable": true,
       "user_found": true,
       "last_change": 18971,
       "min_age": 0,
       "max_age": 99999,
       "warn": 7,
       "inactive": 0,
       "expires": 0
   }
},

With gather_shadow=false, a user entry should look like this:

"root": {
   "name": "root",
   "uid": 0,
   "gid": 0,
   "description": "root",
   "home": "/root",
   "shell": "/bin/bash"
 },

Troubleshooting:

• The script throws errors when executed.
  • Ensure your OS has Bash v4 or higher available. bash --version
• The facts do not appear for the node(s) when I run a playbook.
  • The data should appear under the ansible_local.users fact.
  • SSH into the affected node with the same credentials Ansible uses, and try executing the script manually from the terminal.
  • Ensure that the file has execute permissions added, and that Ansible's connecting user is allowed to read and execute. chmod +x /etc/ansible/facts.d/users.fact
  • Ensure that gather_facts: true is set in your plays
• All of the items under the 'shadow' fact are 0 or empty.
  • If the db_readable fact shows as false, then it means Ansible's connecting user did not have sufficient root permissions to retrieve expiration info from the shadow database. Either add the required sudo/root privileges for the connecting user, or disable gathering shadow data by setting gather_shadow=false in the script.
  • If db_readable is true but user_found is false, then it means the user is missing from the shadow database. This may be due to an improperly-created or defunct user on the system.