Mail::Toaster::Passwd

- NAME
- VERSION
- SYNOPSIS
- DESCRIPTION
- DEPENDENCIES
- METHODS
- AUTHOR
- BUGS
- TODO
- SEE ALSO
- COPYRIGHT AND LICENSE

# NAME

Mail::Toaster::Passwd - add/delete entries from Unix /etc/passwd database

# VERSION

5.07

# SYNOPSIS

Common Unix Passwd functions

# DESCRIPTION

A grouping of frequently used functions I've written for interacting with /etc/passwd entries.

# DEPENDENCIES

Crypt::PasswdMD5 - /usr/ports/security/p5-Crypt-PasswdMD5

# METHODS

new

  Before calling any of the methods, you must create a password object:

        use Mail::Toaster::Passwd;
        my $pass = Mail::Toaster::Passwd->new;

show

  Show user attributes. Right now it only shows quota info.

         $pass->show( {user=>"matt"} );

  input is a hashref

  returns a hashref with error_code and error_desc

delete

  Delete an /etc/passwd user.

        $pass->delete( {user=>"matt"} );

  input is a hashref

  returns a hashref with error_code and error_desc

disable

  Disable an /etc/passwd user by expiring their account.

        $pass->disable( {user=>"matt"} );

  input is a hashref

  returns a hashref with error_code and error_desc

enable

  Enable an /etc/passwd user by removing the expiration date.

        $pass->enable( {user=>"matt"} );

  input is a hashref

  returns a hashref with error_code and error_desc

encrypt

              $pass->encrypt ($pass, $debug)

  encrypt (MD5) the plain text password that arrives at $pass.

exist

  Check to see if a user exists

              $pass->exist($user);

  I use this before adding a new user (easy error trapping) and again after adding a user (to verify success).

              unless ( $pass->exist($user) ) {
                      $pass->user_add( {user=>$user} );
              };

  $user is the username you are adding.

  returns 1 if exists, 0 otherwise

sanity

  Check a password for sanity.

          use Mail::Toaster::Passwd;
          my $pass = Mail::Toaster::Passwd->new();

          $r =  $pass->sanity($password, $username);

          if ( $r->{'error_code'}==100 ) {  print "success"    }
          else                           {  print $r->{'error' };

  $password is the password the user is attempting to use.

  $username is the username the user has selected.

  Checks:

          Passwords must have at least 6 characters.
          Passwords must have no more than 128 characters.
          Passwords must not be the same as the username
          Passwords must not be purely alpha or purely numeric
          Passwords must not be in reserved list
             (/usr/local/etc/passwd.badpass)

  $r is a hashref that gets returned.

  $r->{'error_code'} will contain a result code of 100 (success) or (4-500) (failure)

  $r->{'error_desc'} will contain a string with a description of which test failed.

BackupMasterPasswd

              $pass->BackupMasterPasswd($file)

  Back up the /etc/master.passwd database. This copies $file to a new file named $file.bak.

VerifyMasterPasswd

          my $r = $pass->VerifyMasterPasswd ($passwd, $change, $debug)

          $r->{'error_code'} == 200 ? print "success" : print $r->{'error_desc'};

  Verify that new master.passwd is the right size. I found this necessary on some versions of FreeBSD as a race condition would cause the master.passwd file to get corrupted. Now I verify that after I'm finished making my changes, the new file is a small amount larger (or smaller) than the original.

  $passwd is the filename of your master.passwd file.

  $change is whether the file should ``shrink'' or ``grow''

creategroup

  Installs a system group. The $gid is optional.

          $r = $pass->creategroup($group, $gid)

          $r->{'error_code'} == 200 ? print "success" : print $r->{'error_desc'};

user_add

  Installs a system user. Expects a hashref to be passed containing at least: user. Optional values can be set for: pass, shell, homedir, gecos, quota, uid, gid, expire, domain.

          my $r = $pass->user_add( {user=>"sample"} );

          $r->{'error_code'} == 200 ? print "success" : print $r->{'error_desc'}, "\n";

  returns a HTTP style result code (200 success, 400 bad, 401 unauthorized, 500 error)

user_archive

  Create's a tarball of the users home directory. Typically done right before you rm -rf their home directory as part of a de-provisioning step.

          if ( $prov->user_archive("user") )
          {
              print "user archived";
          };

  returns a boolean.

user_sanity

         $r = $pass->user_sanity($user, $denylist);

         if ( $r->{'error_code'} eq 200 ) {  print "success"    }
         else                             {  print $r->{'error_desc' };

  $user is the username. Pass it along as a scalar (string).

  $denylist is a optional hashref. Define all usernames you want reserved (denied) and it'll check to make sure $user is not in the hashref.

  Checks:

         * Usernames must be between 2 and 16 characters.
         * Usernames must have only lower alpha and numeric chars
         * Usernames must begin with an alpha character
         * Username must not be defined in $denylist hash
         * If the file /usr/local/etc/passwd.reserved exists,
           the username must not exist in that file.

  The format of passwd.reserved is simply one username per line.

      A hashref gets returned that will contain at least error_code, and error_desc.

  $r->{'error_code'} will contain a result code of 0 (failure) or a positive number for (success).

  $r->{'error_desc'} will contain a string with a description of which test failed.

# AUTHOR

Matt Simerson <matt@tnpi.net>

# BUGS

None known. Report any to author.

# TODO

Don't export any of the symbols by default. Move all symbols to EXPORT_OK and explicitely pull in the required ones in programs that need them. - done!

# SEE ALSO

The following are all man/perldoc pages:

     Mail::Toaster
     Mail::Toaster::Conf
     toaster.conf
     toaster-watcher.conf

     http://mail-toaster.org/

# COPYRIGHT AND LICENSE

Copyright (c) 2003-2008, The Network People, Inc. All Rights Reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

Neither the name of the The Network People, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.