NAME
    Passwd::Unix::Alt - Manipulate /etc/{passwd,shadow,group,gshadow}
    entries

VERSION
    version 0.5211

SYNOPSIS
            use Passwd::Unix::Alt;

            my $pu = Passwd::Unix::Alt->new();

            # add a new user
            $pu->user("example", $pu->encpass("my_secret"), $pu->maxuid + 1, 10,
                                              "My User", "/home/example", "/bin/bash");
            die $Passwd::Unix::Alt::errstr if $Passwd::Unix::Alt::errstr;

            # change a user's password
            $pu->passwd("example", $pu->encpass("newsecret"));
            die $Passwd::Unix::Alt::errstr if $Passwd::Unix::Alt::errstr;

            # list users
            foreach my $user ($pu->users) {
                print "Username: $user\nFull Name: ", $pu->gecos($user), "\n\n";
            }

            # get uid
            my $uid = $pu->uid('example');

            # delete user
            $pu->del("example");
            die $Passwd::Unix::Alt::errstr if $Passwd::Unix::Alt::errstr;

            # or

            use Passwd::Unix qw(check_sanity reset encpass passwd_file shadow_file
                                    group_file backup warnings del del_user uid gid gecos
                                    home shell passwd rename maxgid maxuid exists_user
                                    exists_group user users users_from_shadow del_group
                                    group groups groups_from_gshadow);

            user("example", encpass("my_secret"), $pu->maxuid + 1, 10,
                 "My User", "/home/example", "/bin/bash" );
            die $Passwd::Unix::Alt::errstr if $Passwd::Unix::Alt::errstr;

            passwd("example",encpass("newsecret"));
            die $Passwd::Unix::Alt::errstr if $Passwd::Unix::Alt::errstr;

            foreach my $user (users()) {
                print "Username: $user\nFull Name: ", gecos($user), "\n\n";
            }

            my $uid = uid('example');

            del("example");
            die $Passwd::Unix::Alt::errstr if $Passwd::Unix::Alt::errstr;

DESCRIPTION
    The Passwd::Unix module provides an abstract interface to /etc/passwd,
    /etc/shadow and /etc/group format files. It is inspired by
    Unix::PasswdFile module (that one does not handle /etc/shadow file, what
    is necessary in modern systems like Sun Solaris 10 or Linux).

ABOUT PASSWD::UNIX::ALT
    Passwd::Unix::Alt is a fork of Strzelecki Lukasz's Passwd::Unix v0.52,
    which I forked to scratch some of *my* itches, and which I hope can be
    merged back to Passwd::Unix eventually. I use Passwd::Unix because,
    despite its shortcomings, as of mid of 2011 I think it is still the best
    (or perhaps the only functioning) module on CPAN to manipulate passwd
    and shadow entries. As a side note, I originally forked the module to
    create Setup::Unix::User and Setup::Unix::Group. You might want to check
    those two out if you need undo and dry-run capability.

    Notable differences from Passwd::Unix v0.52:

    *   add some tests

    *   does not require root privileges unless necessary (useful for
        testing)

    *   report error string in $Passwd::Unix::Alt::errstr

        Instead of just returning true/false status or carping to stderr.

    *   add lock option

        Currently not enabled by default, needs more testing.

    *   does not use bzip2 for backup files

        I find compression not really necessary yet, plus bzip2 is not
        available in some systems.

    The rest of the documentation is Passwd::Unix's.

ABSTRACT
    Passwd::Unix provides an abstract object-oriented and function interface
    to standard Unix files, such as /etc/passwd, /etc/shadow, /etc/group.
    Additionaly this module provides environment to testing new software,
    without using system critical files in /etc/dir.

SUBROUTINES/METHODS
    new( [ param0 => 1, param1 => 0... ] )
        Constructor. Possible parameters are:

        passwd - path to passwd file; default "/etc/passwd"
        shadow - path to shadow file; default "/etc/shadow"
        group - path to group file; default "/etc/group"
        gshadow - path to gshadow file if any; default "/etc/gshadow"
        umask - umask for creating files; default 0022 (standard for UNIX
        and Linux systems)
        backup - boolean; if set to 1, backup will be made; default 1
        lock - boolean; if set to 1, flock() will be performed before
        modification; default 0
        warnings - boolean; if set to 1, important warnings will be
        displayed; default 0

    check_sanity()
        This method check if environment is sane. I.e. if users in *shadow*
        and in *passwd* are the same. This method is invoked in constructor.

    del( USERNAME0, USERNAME1... )
        This method is an alias for "del_user". It's for transition only.

    del_user( USERNAME0, USERNAME1... )
        This method will delete the list of users. It has no effect if the
        supplied users do not exist.

        Set $Passwd::Unix::Alt::errstr on error.

    del_group( GROUPNAME0, GROUPNAME1... )
        This method will delete the list of groups. It has no effect if the
        supplied groups do not exist.

        Set $Passwd::Unix::Alt::errstr on error.

    encpass( PASSWORD )
        This method will encrypt plain text into unix style MD5 password.

    gecos( USERNAME [,GECOS] )
        Read or modify a user's GECOS string (typically their full name).
        Returns the result of operation (1 or "undef") if GECOS was
        specified. Otherwhise returns the GECOS.

    gid( USERNAME [,GID] )
        Read or modify a user's GID. Returns the result of operation (TRUE
        or FALSE) if GID was specified otherwhise returns the GID.

    home( USERNAME [,HOMEDIR] )
        Read or modify a user's home directory. Returns the result of
        operation (1 or "undef") if HOMEDIR was specified otherwhise returns
        the HOMEDIR.

    maxuid( )
        This method returns the maximum UID in use by all users.

    maxgid( )
        This method returns the maximum GID in use by all groups.

    passwd( USERNAME [,PASSWD] )
        Read or modify a user's password. If you have a plaintext password,
        use the encpass method to encrypt it before passing it to this
        method. Returns the result of operation (1 or "undef") if PASSWD was
        specified. Otherwhise returns the PASSWD.

    rename( OLDNAME, NEWNAME )
        This method changes the username for a user. If NEWNAME corresponds
        to an existing user, that user will be overwritten. It returns FALSE
        on failure and TRUE on success.

    shell( USERNAME [,SHELL] )
        Read or modify a user's shell. Returns the result of operation (TRUE
        or FALSE) if SHELL was specified otherwhise returns the SHELL.

    uid( USERNAME [,UID] )
        Read or modify a user's UID. Returns the result of operation (TRUE
        or FALSE) if UID was specified otherwhise returns the UID.

    user( USERNAME [,PASSWD, UID, GID, GECOS, HOMEDIR, SHELL] )
        This method can add, modify, or return information about a user.
        Supplied with a single username parameter, it will return a six
        element list consisting of (PASSWORD, UID, GID, GECOS, HOMEDIR,
        SHELL), or undef if no such user exists. If you supply all seven
        parameters, the named user will be created or modified if it already
        exists.

        Set $Passwd::Unix::Alt::errstr on error.

    group( GROUPNAME [,GID, ARRAYREF] )
        This method can add, modify, or return information about a group.
        Supplied with a single groupname parameter, it will return a two
        element list consisting of (GID, ARRAYREF), where ARRAYREF is a ref
        to array consisting names of users in this GROUP. It will return
        undef and ref to empty array ("undef, [ ]") if no such group exists.
        If you supply all three parameters, the named group will be created
        or modified if it already exists.

        Set $Passwd::Unix::Alt::errstr on error.

    users()
        This method returns a list of all existing usernames.

    users_from_shadow()
        This method returns a list of all existing usernames in a shadow
        file.

    groups()
        This method returns a list of all existing groups.

    groups_from_gshadow()
        This method returns a list of all existing groups in a gshadow file.

    exists_user(USERNAME)
        This method checks if specified user exists. It returns TRUE or
        FALSE.

    exists_group(GROUPNAME)
        This method checks if specified group exists. It returns TRUE or
        FALSE.

    default_umask([UMASK])
        This method, if called with an argument, sets default umask for this
        module (not Your program!). Otherwise returns the current UMASK.
        Probably You don't want to change this.

    passwd_file([PATH])
        This method, if called with an argument, sets path to the *passwd*
        file. Otherwise returns the current PATH.

    shadow_file([PATH])
        This method, if called with an argument, sets path to the *shadow*
        file. Otherwise returns the current PATH.

    group_file([PATH])
        This method, if called with an argument, sets path to the *group*
        file. Otherwise returns the current PATH.

    gshadow_file([PATH])
        This method, if called with an argument, sets path to the *gshadow*
        file. Otherwise returns the current PATH.

    reset()
        This method sets paths to files *passwd*, *shadow*, *group* to the
        default values.

DEPENDENCIES
    Struct::Compare
    Crypt::PasswdMD5

INCOMPATIBILITIES
    None known.

BUGS AND LIMITATIONS
    None. I hope.

THANKS
    Thanks to Jonas Genannt for suggestions as well as supplying relevant
    patch!
    BIG THANKS to Lopes Victor for reporting some bugs and his exact
    sugesstions :-)
    Thanks to Foudil BRÉTEL for some remarks, suggestions as well as
    supplying relevant patch!
    BIG thanks to Artem Russakovskii for reporting a bug.

AUTHOR
    Strzelecki Lukasz <strzelec@rswsystems.com>

LICENCE AND COPYRIGHT
    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    See http://www.perl.com/perl/misc/Artistic.html

AUTHOR
    Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2012 by Steven Haryanto.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.

