userlist

#! /bin/sh
# userlist (Bourne shell script) -- list one or all users, with password and expiry info
#
# Version: 1.3.2
# Copyright: (c) 2014 Alastair Irvine <alastair@plug.org.au>
# Keywords: users passwd group gecos expiry
# Licence: This file is released under the GNU General Public License
#
# See help() for usage.
#
# Note: Because it accesses the shadow database, userlist should be run as root.
#       Otherwise it shows a warning and a minimal listing equivalent to -u.
# 
# Licence details:
#     This program is free software; you can redistribute it and/or modify
#     it under the terms of the GNU General Public License as published by
#     the Free Software Foundation; either version 2 of the License, or (at
#     your option) any later version.
#
#     See http://www.gnu.org/licenses/gpl-2.0.html for more information.
#
#     You can find the complete text of the GPLv2 in the file
#     /usr/share/common-licenses/GPL-2 on Debian systems.
#     Or see the file COPYING in the same directory as this program.
#
#
# TO-DO:
#   + Rainbow mode, which outputs all 14 pieces of information printed
#     for each user in a different colour.
#   + Output phone numbers, etc.
#   + research: does today have to be past the expiry date to count as expired
#   + option to sort output by various criteria
#   + expand @<groupname> or %<groupname> into a list of users
#   + test for min_age > max_age; this means user cannot change her password
#   + handle max_age == 0 (this isn't valid)


self=`basename $0`
allowed_options=s:xXdqvhcCwogu
allowed_long_options=verbose,colour,color,wrap,oneline,help,unprivileged
today=$(($(date +%s) / 86400))


# *** FUNCTIONS ***
help()
{
  cat << EOT_HELP
Usage: userlist [-x|-X| -s <status>] [-q] [-v [-v [-f]] [-w]] [<username> ...]

By default, shows all users, except system users (i.e. UID < 500) and
disabled users (i.e. password crypt is equal to * (or !*); these were
usually added by a package).  If specific usernames are provided, they
are always shown (i.e. -s, -x and -X don't apply).

Functionality and information is reduced if not run as root.

Options:
  -u            Unprivileged mode (auto. with warning if not running as root)
  -x            Also show accounts added by packages
  -X            Show all accounts including system accounts
  -s <status>   Show only accounts with this status (never system users)
  -q            Don't show a header line
  -v, --verbose Show a second, indented line per user with gecos info, IDs, etc.
  -vv           Show phone numbers, etc.
  -o, --oneline Don't wrap -v output
  -g            Show group info
  -c, --colour  Colourise output, but only if STDOUT is a terminal
  -C            Still colourise output even if STDOUT isn't a terminal
                (which is useful if piping to less -R)
  -d            (debug mode) displays shadow file entries to STDERR
  -h, --help    Show this help

Output:
  The Status column is one of: active, disabled, expired.
  If appropriate, it will show a reason in parentheses:
    auto means password_age > Max + Grace
    admin means account has been manually expired by the sysadmin
  (Note: This column is limited in unprivileged mode, and is left out unless
  verbose mode is active.)

  The Password column is one of: set, locked, LOCKED, BLANK, none, old.
  (Or "future", which only happens if the password age is negative.)

  The Remaining, Age, Warn, Min., Max., Grace (a.k.a. inactivity) columns are
  all given in terms of days.  See shadow(5) for more information.
  Remaining (pertaining to account expiry) and Age (of password) are calculated
  by userlist, relative to today.

Important info:
  "LOCKED" is a blank password that is locked, which isn't dangerous because
  passwd refuses to unlock an account if doing so would make it passwordless.

  "none" means a specific invalid crypt, used to create the account disabled.

  SSH keys (or other methods, if configured), can be used to log into
  *any* account with *any* Status (except "expired") or Password state.
  (This assumes that SSH obeys PAM config.  "PermitEmptyPasswords no" won't
  prevent logins via an SSH key.)
EOT_HELP

  exit
}


# Expects a list of users in passwd(5) format on stdin
process_users_full()
{
  if [ $output_header = y ] ; then
    # $bold and $normal aren't defined unless $colour != no
    printf "$bold$username_header_format %-10s\
%9s  %s %4s  %5s  %5s  %5s  %5s$normal" \
      Username Status Remaining Password Age 'Warn' 'Min.' 'Max.' 'Grace'
    ## .. 'Warn for' 'Min. age' 'Max. age' 'Grace period'
    if [ $verbose -ge 1 ] ; then
      printf "$eol$bold  $passwd_header_format$normal" \
        "Full name" UID GID "Login shell" "Home directory"
      ## # output phone numbers, etc.
      ## if [ $verbose -ge 2 ] ; then
      ##   printf "  \n" ...
      ## fi
    fi
    # "continue' the line or just end it depending on whether there's more info
    show_groups_header
  fi
  while IFS=: read username passwd uid gid gecos homedir loginshell _
  do
    [ $debug -gt 0 ] && echo "()" >&2
    if [ $include_sys = all -o $uid -ge 500 -a $uid != 65534 ] ; then
      getent shadow "$username" | \
        while IFS=: read username passwd_crypt change_date min_age max_age warn_days grace_days expire_date
        do
          [ $debug -gt 0 ] && echo "($username $passwd_crypt $change_date $min_age $max_age $warn_days $grace_days $expire_date)" >&2
          # See if the account is active, i.e. unexpired
          status=active     # this is a default
          status_shown=     # will be set to $status if not set
          if [ -z "$expire_date" ] ; then
            remaining_days=-
          else
            if [ $expire_date -lt $today ] ; then
              status=expired
            fi
            # test for special case dates
            if [ $expire_date = 0 -o $expire_date = 1 ] ; then
              # first part appears to be adjacent to the previous column
              remaining_days=0
              status=expired
              status_shown="expired (admin)"
            else
              remaining_days=$(($expire_date - $today))
            fi
          fi
          # If it passed the expiry check, test the shell
          if [ $status = active ] ; then
            if [ "$shell" = /usr/sbin/nologin -o "$shell" = /bin/false ] ; then
              status=disabled
            else
              if [ -z "$shell" ] ; then
                shell=NONE
              fi
            fi
          fi
          case "$passwd_crypt" in
            '')  pwstatus=BLANK ;;
            !\*) pwstatus=none ;;
            \*)  pwstatus=none ;;
            \!)  pwstatus=LOCKED ;;
            \!*) pwstatus=locked ;;
            *)   pwstatus=set ;;
          esac
          case "$change_date" in
            '') pw_age=N/A ;;
            0)  pw_age=change ;;
            *)  pw_age=$(($today - $change_date))
                # Handle the cases where the password appears to have been
                # changed in the future, or has expired
                if [ $pw_age -lt 0 ] ; then
                  pwstatus=future
                elif [ -n "$max_age" ] ; then
                  # Note that pw_age will still be set if the password is
                  # locked or empty
                  if [ "$max_age" -ge 0 -a "$pw_age" -gt "$max_age" ] ; then
                    if [ $pwstatus = set ] ; then
                      pwstatus=old
                    fi
                    # Check for the auto-expired state
                    if [ -z "$grace_days" ] ; then
                      grace_days=0
                    fi
                    if [ $pw_age -gt $(($max_age + $grace_days)) ] ; then
                      status=expired
                      status_shown="expired (auto)"
                    fi
                  fi
                else
                  # This is the implied meaning of a blank field
                  max_age=-1
                fi
                ;;
          esac

          # Mark users with * for a crypt as disabled, i.e. can't log in with password
          if [ $pwstatus = none ] ; then
            status=disabled
          fi
          if [ -z "$status_shown" ] ; then
            status_shown=$status
          fi

          # Only output if conditions match
          if [ $status = "$desired_status" -o \
               -z "$desired_status" -a \
               \( $status != disabled -o $include_sys != none \) ] ; then
            printf "$username_field_format \
$status_field_format%4s  %-6s %6s  %5d  %5d  %5d  %5d" \
              "$username" \
              "$status_shown" "$remaining_days" "$pwstatus" "$pw_age" $warn_days $min_age $max_age $grace_days
            ## %8d  %8d  %8d  %12d
            if [ $verbose -ge 1 ] ; then
              # Print regular info from the passwd db, but strip phone number etc.
              printf "$eol  $passwd_field_format" \
                "${gecos%%,*}" $uid $gid "$loginshell" $homedir
              ## # output phone numbers, etc.
              ## if [ $verbose -ge 2 ] ; then
              ##   printf "$eol  " ...
              ## fi
            fi
            # "continue' the line or just end it depending on whether there's more info
            show_groups $username
          fi
        done
    fi
  done
}


# Expects a list of users in passwd(5) format on stdin
process_users_minimal()
{
  if [ $output_header = y ] ; then
    # $bold and $normal aren't defined unless $colour != no
    printf "$bold$username_header_format \
$([ $verbose -ge 1 ] && echo "$status_field_format  ")\
$passwd_header_format$normal" \
        Username $([ $verbose -ge 1 ] && echo Status) \
        "Full name" UID GID "Login shell" "Home directory"
      ## # output phone numbers, etc.
      ## if [ $verbose -ge 2 ] ; then
      ##   printf "$eol  " ...
      ## fi
    # "continue' the line or just end it depending on whether there's more info
    show_groups_header
  fi
  while IFS=: read username passwd uid gid gecos homedir loginshell _
  do
    if [ $include_sys = all -o $uid -ge 500 -a $uid != 65534 ] ; then
      # See if the account is active, i.e. unexpired
      status=active     # this is a default
      if [ "$shell" = /usr/sbin/nologin -o "$shell" = /bin/false ] ; then
        status=disabled
      else
        if [ -z "$shell" ] ; then
          shell=NONE
        fi
      fi
          
      # Print unprivileged mode output, maybe with status if requested.
      # (Strip phone number etc. from regular info from the passwd db.)
      # Warning: $status can only ever be one word.
      # (It only appears as a printf argument under some circumstances,
      # i.e. sometimes the $() output is nothing, an so can't be quoted.)
      printf "$username_field_format \
$([ $verbose -ge 1 ] && echo "$status_field_format  ")$passwd_field_format" \
        "$username" $([ $verbose -ge 1 ] && echo $status) \
        "${gecos%%,*}" $uid $gid $loginshell $homedir
      ## # output phone numbers, etc.
      ## if [ $verbose -ge 2 ] ; then
      ##   printf "$eol  " ...
      ## fi
      # "continue' the line or just end it depending on whether there's more info
      show_groups $username
    fi
  done
}


show_groups_header()
{
  if [ $show_groups = y ] ; then
    printf "$eol$bold  %s$normal\n" Groups
  else
    echo
  fi
}


# Expects a username in $1
show_groups()
{
  if [ $show_groups = y ] ; then
    # Output the groups, stripping off the "<username> : " prefix
    local groups="$(groups $1)"
    printf "$eol  %s\n" "${groups#* : }"
  else
    echo
  fi
}


# *** MAINLINE ***
# == command-line parsing ==
# -- defaults --
process_fn=process_users_full
include_sys=none
output_header=y
eol="\n"
debug=0
verbose=0
colour=no
show_groups=n

# -- option handling --
set -e
orthogonal_opts=$(getopt --shell=sh --name=$self \
  --options=+$allowed_options --longoptions=$allowed_long_options -- "$@")
eval set -- "$orthogonal_opts"
set +e      # getopt would have already reported the error

while [ x"$1" != x-- ] ; do
  case "$1" in
    -u|--unprivileged) process_fn=process_users_minimal ;;
    -g) show_groups=y ;;
    -s) desired_status="$2" ; shift ;;
    -x) include_sys=some ;;
    -X) include_sys=all ;;
    -q) output_header=n ;;
    -o|--oneline) eol= ;;   # no need for content: next line starts with "  "
    -w|--wrap) eol="\n" ;;  # restore default
    -c|--colour|--color) colour=yes ;;
    -C) colour=force ;;
    -d) debug=$((debug + 1)) ;;
    -v|--verbose) verbose=$((verbose + 1)) ;;
    -h|--help) help ;;
    -1) echo "${self}: Warning: Blah blah blah feature unsupported" >&2 ;;
  esac
  shift       # get rid of the option (or its arg if the inner shift already got rid it)
done
shift       # get rid of the "--"


# == sanity checking ==
# Check if an unprivileged user forgot the -u option
if [ $(id -u) != 0 -a $process_fn = process_users_full ] ; then
  echo "${self}: Warning: Not running as root; activating unprivileged mode." >&2
  process_fn=process_users_minimal
fi


# == preparation ==
if [ $colour = yes -a -t 1 -o $colour = force ] ; then
  bold=$(setterm -bold on)
  normal=$(setterm -bold off)
fi

# $gecos(trimmed) $uid $gid $loginshell $homedir
# (Allow longer/unlimited field lengths (e.g. for $homedir) in oneline mode.)
if [ -z "$eol" ] ; then
  passwd_header_format="%-19s  %5s:%-5s  %-18s  %-30s"
  passwd_field_format="%-19.19s  %5d:%-5d  %-18s  %-30s"
  username_header_format="%-16s"
  username_field_format="%-16.16s"
else
  # the unrestricted field on the end lets longer homedirs wrap when necessary
  passwd_header_format="%-19s  %5s:%-5s  %-12s  %s"
  passwd_field_format="%-19.19s  %5d:%-5d  %-12s  %s"
  # There's more info in unprivileged mode, so make username column narrower
  # (but only in multiline mode)
  if [ $process_fn = process_users_minimal ] ; then
    username_header_format="%-11s"
    username_field_format="%-11.11s"
  else
    username_header_format="%-16s"
    username_field_format="%-16.16s"
  fi
fi
if [ $process_fn = process_users_minimal ] ; then
  status_field_format="%-8s"
else
  status_field_format="%-15s"
fi


# == processing ==
# check if a username was supplied
if [ $# -gt 0 ] ; then
  include_sys=all
  for username ; do
    getent passwd "$username"
  done | $process_fn
else
  getent passwd | $process_fn
fi