NAME

Plugtools - LDAP and Posix

VERSION

Version 1.3.0

SYNOPSIS

    use Plugtools;

    my $pt = Plugtools->new();
    ...

METHODS

new

Initiate Plugtools.

Only one arguement is accepted and that is a hash.

args hash

At this time, none of these values are required.

config

This specifies a config file to read other than the default.

    #initilize it and read the default config
    my $pt=Plugtools->new();
    if($pt->{error}){
        print "Error!\n";
    }

    #initilize it and read '/some/config'
    my $pt=Plugtools->new({ config=>'/some/config' });
    if($pt->{error}){
        print "Error!\n";
    }

addGroup

args hash

group

This is the group name to add.

gid

This is the numeric ID of the group to add. If it is not defined, it will automatically be added.

dump

If this is true, call the dump method on the create Net::LDAP::Entry object.

    #the most basic form
    $pt->addGroup({
                   group=>'someGroup',
                   })
    if($pt->{errpr}){
        print "Error!\n";
    }

    #do more
    $pt->addGroup({
                   group=>'someGroup',
                   gid=>'4444',
                   dump=>'1',
                   })
    if($pt->{errpr}){
        print "Error!\n";
    }

addUser

args hash

user

The user to create.

uid

The numeric user ID for the new user. If this is note defined, the first free one will be used.

group

The primary group of user. If this is not defined, the username is used. If the user is this is not defined, it will be set to the same as the user.

gid

If this is defined, the specified GID will be used instead of automatically assigning one.

gecos

The gecos field for the user. If this is not defined, it is set to the user name.

shell

This is the shell for the user. If this is not defined, the default one is used.

home

This is the home directory for the user. If this is not defined, the home prototype is used.

createHome

If this is specified, the default value for createHome will be overrode the defaults or what is specified in the config.

If it exists, it assumes it does not need to be created, but it will still be chowned.

skel

Use this instead of the default skeleton or the one specified in the config file.

This is skipped, if the home already exists.

chmodValue

Overrides the default value for this or the one specified in the config.

chmodHome

Overrides the default value for this or the one specified in the config.

chownHome

If home should be chowned. This overrides the value specified in the config or the default one.

dump

If this is true, call the dump method on the create Net::LDAP::Entry object.

    #the most basic form
    $pt->addUser({
                  user=>'someUser',
                  })
    if($pt->{errpr}){
        print "Error!\n";
    }

    #do more
    $pt->addUser({
                  user=>'someUser',
                  uid=>'3333',
                  group=>'someGroup',
                  gid=>'4444',
                  dump=>'1',
                   })
    if($pt->{errpr}){
        print "Error!\n";
    }

connect

This forms a LDAP connection using the information in config file.

    my $ldap=$pt->connect;
    if($pt->{error}){
        print "Error!\n";
    }

deleteGroup

This removes a group.

    $pt->deleteGroup('someGroup');
    if($pt->{error}){
        print "Error!\n";
    }

deleteUser

This removes a user.

Only LDAP is touched at this time, so if a user is a member of a group setup in '/etc/groups', then it won't be removed from that group.

This does not remove the user's old home directory.

arge hash

'user' is the only required value.

user

This is the user to be removed.

removeHome

This removes the home directory of the user.

removeGroup

Remove the primary group if it is empty.

    #the most basic form
    $pt->deleteUser({
                  user=>'someUser',
                  })
    if($pt->{errpr}){
        print "Error!\n";
    }

    #do more
    $pt->deleteUser({
                     user=>'someUser',
                     removeHome=>'1',
                     removeGroup=>'0',
                     })
    if($pt->{errpr}){
        print "Error!\n";
    }

findGroupDN

This locates a DN for a already setup group.

    my $dn=$pt->findGroupDN('someGroup');
    if($pt->{error}){
        print "Error!";
    }

findUserDN

This locates a DN for a already setup group.

    my $dn=$pt->findUserDN('someUser');
    if($pt->{error}){
        print "Error!";
    }

getUserEntry

Fetch a Net::LDAP::Entry object of a user.

args hash

user

This is the user to fetch a Net::LDAP::Entry of.

    my $entry=$pt->getUserEntry({
                                 user=>'someUser',
                                 });
    if($pt->{error}){
        print "Error!\n";
    }

groupAddUser

This adds a user from a group.

args hash

group

The group to act on.

user

The user to act remove from the group.

dump

Call the dump method on the entry afterwards.

    $pt->groupAddUser({
                       group=>'someGroup',
                       user=>'someUser',
                       })
    if($pt->{errpr}){
        print "Error!\n";
    }

groupGIDchange

This changes the GID for a group.

args hash

group

The group to act on.

gid

The GID to change this group to.

userUpdate

Update any user that has the old GID as their primary GID. This defaults to true, '1'.

dump

Call the dump method on the group afterwards.

    $pt->groupGIDchange({
                         group=>'someGroup',
                         gid=>'2222',
                         })
    if($pt->{errpr}){
        print "Error!\n";
    }

groupRemoveUser

This removes a user from a group.

args hash

group

The group to act on.

user

The user to act remove from the group.

dump

Call the dump method on the group afterwards.

    $pt->groupRemoveUser({
                       group=>'someGroup',
                       user=>'someUser',
                       })
    if($pt->{errpr}){
        print "Error!\n";
    }

groupClean

This checks through the groups setup in LDAP and removes any group that does not exist.

args hash

dump

If this is specified, the dump method is called on any updated entry. If this is not defined, it defaults to false.

    $pt->groupClean;
    if($pt->{error}){
        print "Error!\n";
    }

    #do the same thing as above, but do $entry->dump for any changed entry
    $pt->groupClean({dump=>'1'});
    if($pt->{error}){
        print "Error!\n";
    }

isLDAPgroup

This tests if a group is in LDAP or not.

    my $returned=$pt->isLDAPgroup('someGroup');
    if($pt->{error}){
        print "Error!\n";
    }else{
        if($returned){
            print "Yes!\n";
        }else{
            print "No!\n";
        }
    }

isLDAPuser

This tests if a group is in LDAP or not.

    my $returned=$pt->isLDAPuser('someUser');
    if($pt->{error}){
        print "Error!\n";
    }else{
        if($returned){
            print "Yes!\n";
        }else{
            print "No!\n";
        }
    }

onlyMember

This figures out if a user is the only member of a group.

This returns true if the user is the only member of that group. A value of false means that user is not in that group and there are no members or that it that there are other members.

args hash

Both 'user' and 'group' are required.

user

This is the user it is checking to see if it is the only member of a group.

group

This is the group to check.

    my $returned=$pt->onlyMember({
                       user=>'someUser',
                       group=>'someGroup',
                       });
    if($pt->{error}){
        print "Error!\n";
    }

plugin

This processes series plugins.

opts hash

This is the first required hash.

ldap

This is the current LDAP connect.

This contains the variable it should reference for what plugins to run.

entry

This is the LDAP entry to work on.

args hash

This is the hash that was passed to the function calling the plugin.

removeUserFromGroups

This removes a user from any group in LDAP they are a member of.

No checks are made to see if the user exists or not.

    $pt->removeUserFromGroups('someUser');
    if($pt->{error}){
        print "Error!\n";
    }

readConfig

This reads the specified config.

    #reads the default config
    $pt->readConfig();
    if($pt->{error}){
        print "Error!";
    }

    #reads the config '/some/config'
    $pt->readConfig('/some/config');
    if($pt->{error}){
        print "Error!";
    }

userGECOSchange

This changes the UID for a user.

args hash

user

The user to act on.

gecos

The GECOS to change this user to.

dump

Call the dump method on the group afterwards.

    $pt->userGECOSchange({
                          user=>'someUser',
                          gecos=>'whatever',
                          });
    if($pt->{error}){
        print "Error!\n";
    }

userShellChange

This changes the UID for a user.

args hash

user

The user to act on.

shell

The shell to change this user to.

dump

Call the dump method on the group afterwards.

    $pt->userShellChange({
                          user=>'someUser',
                          shell=>'/bin/tcsh',
                          });
    if($pt->error){
        print "Error!\n";
    }

userSetPass

This changes the password for a user.

args hash

user

This is the user to act on.

pass

This is the new password to set.

    $pt->userSetPass({
                      user=>'someUser',
                      pass=>'whatever',
                      });
    if($pt->{error}){
        print "Error!\n";
    }

userGIDchange

This changes the UID for a user.

args hash

user

The user to act on.

gid

The GID to change this user to. This GID must already exist.

dump

Call the dump method on the group afterwards.

    $pt->userGIDchange({
                        user=>'someUser',
                        gid=>'1234',
                        });
    if($pt->{error}){
        print "Error!\n";
    }

userUIDchange

This changes the UID for a user.

args hash

user

The user to act on.

uid

The UID to change this user to.

dump

Call the dump method on the group afterwards.

    $pt->userUIDchange({
                        user=>'someUser',
                        uid=>'1234',
                        });
    if($pt->{error}){
        print "Error!\n";
    }

error

Returns the current error code and true if there is an error.

If there is no error, undef is returned.

    my $error=$foo->error;
    if($error){
        print 'error code: '.$error."\n";
    }

errorblank

This is a internal function and should not be called.

errorString

Returns the error string if there is one. If there is not, it will return ''.

    my $error=$foo->error;
    if($error){
        print 'error code:'.$error.': '.$foo->errorString."\n";
    }

ERROR CODES

15

The group does not exist in LDAP or under specified group base.

18

The user does not exist in LDAP or under specified user base.

22

Copying the skeleton to the home location failed.

25

Failed to update a entry when removing a memberUid.

26

Failed to remove the users home directory.

27

Faild to fetch a list posixGroup objects.

29

Failed to update the entry when changing the GID.

31

Failed to update the entry when changing the UID.

34

Failed to update the entry when changing the GECOS.

36

Updating the password for the user failed.

37

Errored when fetching a list of users that may possibly need updated.

40

The specified selection of plugins to run does not exist.

43

$opts{entry} is not a Net::LDAP::Entry object.

46

Calling the LDAP update function on the entry modified by the userSetPass plugin failed. The unix password has been set though.

CONFIG FILE

The default is xdg_config_home().'/plugtoolsrc', which wraps around to "~/.config/plugtoolsrc". The file format is ini.

The only required ones are 'bind', 'pass', 'groupbase', and 'userbase'.

    bind=cn=admin,dc=foo,dc=bar
    pass=somebl00dyp@ssw0rd
    userbase=ou=users,dc=foo,dc=bar
    groupbase=ou=groups,dc=foo,dc=bar

userbase

This is the base for where the users are located.

groupbase

This is the base where the groups are located.

server

This is the LDAP server to connect to. If the server is not specified, '127.0.0.1' is used.

port

This is the LDAP port to use. If the port is not specified, '389' is used.

UIDstart

This is the first UID to start checking for existing users at. The default is '1001'.

GIDstart

This is the first GID to start checking for existing groups at. The default is '1001'.

defaultShell

This is the default shell for a user. The default is '/bin/tcsh'.

HOMEproto

The prototype for the home directory. %%USERNAME%% is replaced with the username. The default is '/home/%%USERNAME%%/'.

skeletonHome

This is the location that will be copied for when creating a new home directory. If this is not defined, a blanked one will be created. The default is '/etc/skel'.

chmodValue

This is the numeric value the newly created home directory will be chmoded to. The default is '640'.

chmodHome

If home should be chmoded. The default value is '1', true.

chownHome

If home should be chowned. The default value is '1', true.

createHome

If this is true, it the home directory for the user will be created. The default is '1'.

groupPrimary

This is the attribute to use for when creating the DN for the group entry. Either 'cn' or 'gidNumber' are currently accepted. The default is 'cn'.

userPrimary

This is the attribute to use for when creating the DN for the user entry. Either 'cn', 'uid', or 'uidNumber' are currently accepted. The default is 'uid'.

starttls

Wether or not it should try to do start_tls.

TLSverify

The verify mode for TLS. The default is 'none'.

none

The server may provide a certificate but it will not be checked - this may mean you are be connected to the wrong server.

optional

Verify only when the server offers a certificate.

require

The server must provide a certificate, and it must be valid.

SSLversion

This is the SSL versions accepted.

'sslv2', 'sslv3', 'sslv2/3', or 'tlsv1' are the possible values. The default is 'tlsv1'.

SSLciphers

This is a list of ciphers to accept. The string is in the standard OpenSSL format. The default value is 'ALL'.

removeGroup

This determines if it should try to remove the user's primary group after removing the user.

The default value is '1', true.

removeHome

This determines if it should try to remove a user's home directory when deleting the user.

The default value is '0', false.

userUpdate

This determines if it should update the primary GIDs for users after groupGIDchange has been called.

The default value is '1', true.

pluginAddGroup

A comma seperated list of plugins to run when addGroup is called.

pluginAddUser

A comma seperated list of plugins to run when addUser is called.

pluginGroupAddUser

A comma seperated list of plugins to run when groupAddUser is called.

pluginGroupGIDchange

A comma seperated list of plugins to run when groupGIDchange is called.

pluginGroupRemoveUser

A comma seperated list of plugins to run when groupRemoveUser is called.

pluginUserGECOSchange

A comma seperated list of plugins to run when userGECOSchange is called.

pluginUserSetPass

A comma seperated list of plugins to run when userSetPass is called.

pluginUserGIDchange

A comma seperated list of plugins to run when userGIDchange is called.

pluginUserShellChange

A comma seperated list of plugins to run when userShellChange is called.

pluginUserUIDchange

A comma seperated list of plugins to run when userUIDchange is called.

pluginDeleteUser

A comma seperated list of plugins to run when deleteUser is called.

pluginDeleteGroup

A comma seperated list of plugins to run when deleteGroup is called.

PLUGINS

Plugins are supported by the functions specified in the config section.

A plugin may be specified for any of those by setting that value to a comma seperated list of plugins. For example if you wanted to call 'Plugtools::Plugins::Dump' and then 'Foo::Bar' for a userSetPass, you would set the value 'pluginsUserSetPass' equal to 'Plugtools::Plugins::Dump,Foo::Bar'.

Both hashes specified in the section covering the plugin function. The key 'self' is added to %opts before it is passed to the plugin. That key contains a copy of the Plugtools object.

A plugin is a Perl module that is used via eval and then the function 'plugin' is called on it. The expected return is

The plugin is called before the update method is called on a Net::LDAP::Entry object, except for the function 'userSetPass'. It is called after the password is updated.

example

What is shown below is copied from Plugtools::Plugins::Dump. This is a simple plugin that calls Data::Dumper->Dumper on what is passed to it.

    package Plugtools::Plugins::Dump;
    use warnings;
    use strict;
    use Data::Dumper;
    our $VERSION = '0.0.0';
    sub plugin{
        my %opts;
        if(defined($_[1])){
            %opts= %{$_[1]};
        };
        my %args;
        if(defined($_[2])){
                %args= %{$_[2]};
        };
        print '%opts=...'."\n".Dumper(\%opts)."\n\n".'%args=...'."\n".Dumper(\%args);
        my %returned;
        $returned{error}=undef;
        return %returned;
    }
        1;

AUTHOR

Zane C. Bowers, "<vvelox at vvelox.net>"

BUGS

Please report any bugs or feature requests to "bug-plugtools at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Plugtools>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Plugtools

You can also look for information at:

RT: CPAN's request tracker
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Plugtools>
AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/Plugtools>
CPAN Ratings
<http://cpanratings.perl.org/d/Plugtools>
Search CPAN
<http://search.cpan.org/dist/Plugtools/>

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

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