NAME

Linux::Shadow - Perl extension for accessing the shadow files using the standard libc shadow routines.

SYNOPSIS

  use Linux::Shadow;
  ($name,$passwd,$lstchg,$min,$max,$warn,$inact,$expire,$flag) = getspnam('user');
  ($name,$passwd,$lstchg,$min,$max,$warn,$inact,$expire,$flag) = getspent();
  setspent();
  endspent();
  
  use Linux::Shadow qw(:getpw);
  ($name,$passwd,$uid,$gid, $quota,$comment,$gcos,$dir,$shell,$expire) = getpwnam('user');
  ($name,$passwd,$uid,$gid, $quota,$comment,$gcos,$dir,$shell,$expire) = getpwuid(0);
  ($name,$passwd,$uid,$gid, $quota,$comment,$gcos,$dir,$shell,$expire) = getpwent();

DESCRIPTION

Perl gives access to the user's shadow password itself via getpw*, but the rest of the shadow entry is not available (expire is theoretically available if compiled that way, but it isn't universal). This module provides a Perl interface to the shadow routines getspnam, getspent, setspent and endspent, allowing the full shadow password structure to be returned. Like all access to the shadow files, root privileges are required to return anything - non- root users get nothing.

SUBROUTINES

Default Exports

These routines are exported by default, as they simply expose identically named C library routines that are not a part of Perl's core.

getspnam(NAME)

Return the shadow entry of the listed user as an array. If the user doesn't exist, or an error occurs, returns an empty array.

getspent()

Return the shadow entry of the next user in the shadow file starting with the first entry the first time getspent() is called. Returns and empty array once the end of the shadow file is reached or an error occurs.

setspent()

Resets the pointer in the shadow file to the beginning.

endspent()

Releases the resources used to access the shadow file.

Exportable constants

  SHADOW - the path of the system shadow file

This is not exported by default. You can get both this constant and the exported functions by using the ':all' tag.

Overloaded Core Routines

These routines overload the identically named Perl core routines, with the purpose of populating the $expires field that is not typically compiled into Perl itself. These must be explicitly imported to access them.

getpwnam(NAME)

getpwuid(UID)

getpwent

These functions work exactly like the identically named functions documented in "perlfunc" in perlfunc, except that if they return the userinfo and can access the shadow info, the $expires field is guaranteed to be populated. See "getpwnam" in perlfunc for details.

RETURN VALUES

Shadow Entry

The shadow entry returned by getspnam and getspent is an array of 9 items as follows:

name

The user login name.

passwd

The user's encrypted password.

lstchg

The number of days since Jan 1, 1970 password was last changed.

min

The number of days before which password may not be changed.

max

The number of days after which password must be changed.

warn

The number of days before password is to expire that user is warned of pending password expiration.

inact

The number of days after password expires that account is considered inactive and disabled.

expire

The number of days since Jan 1, 1970 when account will be disabled.

flag

This field is reserved for future use.

FILES

These functions rely on the system shadow file, which is usually /etc/shadow.

CAVEATS

Access to the shadow file requires root privileges, or possibly membership in the shadow group if it exists (this is OS/distribution-specific). Calling getspnam or getspent without as a non- root user will return nothing.

SEE ALSO

shadow(3), getspnam(3), "getpwnam" in perlfunc

AUTHOR

Joshua Megerman, <josh@honorablemenschen.com<gt>

COPYRIGHT AND LICENSE

Copyright (C) 2017 by Joshua Megerman

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.16.3 or, at your option, any later version of Perl 5 you may have available.

cpanm Linux::Shadow

perl -MCPAN -e shell
install Linux::Shadow