Plugtools - LDAP and Posix
Version 1.3.0
use Plugtools; my $pt = Plugtools->new(); ...
Initiate Plugtools.
Only one arguement is accepted and that is a hash.
At this time, none of these values are required.
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"; }
This is the group name to add.
This is the numeric ID of the group to add. If it is not defined, it will automatically be added.
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"; }
The user to create.
The numeric user ID for the new user. If this is note defined, the first free one will be used.
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.
If this is defined, the specified GID will be used instead of automatically assigning one.
The gecos field for the user. If this is not defined, it is set to the user name.
This is the shell for the user. If this is not defined, the default one is used.
This is the home directory for the user. If this is not defined, the home prototype is used.
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.
Use this instead of the default skeleton or the one specified in the config file.
This is skipped, if the home already exists.
Overrides the default value for this or the one specified in the config.
If home should be chowned. This overrides the value specified in the config or the default one.
#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"; }
This forms a LDAP connection using the information in config file.
my $ldap=$pt->connect; if($pt->{error}){ print "Error!\n"; }
This removes a group.
$pt->deleteGroup('someGroup'); if($pt->{error}){ print "Error!\n"; }
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.
'user' is the only required value.
This is the user to be removed.
This removes the home directory of the user.
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"; }
This locates a DN for a already setup group.
my $dn=$pt->findGroupDN('someGroup'); if($pt->{error}){ print "Error!"; }
my $dn=$pt->findUserDN('someUser'); if($pt->{error}){ print "Error!"; }
Fetch a Net::LDAP::Entry object of a user.
This is the user to fetch a Net::LDAP::Entry of.
my $entry=$pt->getUserEntry({ user=>'someUser', }); if($pt->{error}){ print "Error!\n"; }
This adds a user from a group.
The group to act on.
The user to act remove from the group.
Call the dump method on the entry afterwards.
$pt->groupAddUser({ group=>'someGroup', user=>'someUser', }) if($pt->{errpr}){ print "Error!\n"; }
This changes the GID for a group.
The GID to change this group to.
Update any user that has the old GID as their primary GID. This defaults to true, '1'.
Call the dump method on the group afterwards.
$pt->groupGIDchange({ group=>'someGroup', gid=>'2222', }) if($pt->{errpr}){ print "Error!\n"; }
This removes a user from a group.
$pt->groupRemoveUser({ group=>'someGroup', user=>'someUser', }) if($pt->{errpr}){ print "Error!\n"; }
This checks through the groups setup in LDAP and removes any group that does not exist.
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"; }
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"; } }
my $returned=$pt->isLDAPuser('someUser'); if($pt->{error}){ print "Error!\n"; }else{ if($returned){ print "Yes!\n"; }else{ print "No!\n"; } }
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.
Both 'user' and 'group' are required.
This is the user it is checking to see if it is the only member of a group.
This is the group to check.
my $returned=$pt->onlyMember({ user=>'someUser', group=>'someGroup', }); if($pt->{error}){ print "Error!\n"; }
This processes series plugins.
This is the first required hash.
This is the current LDAP connect.
This contains the variable it should reference for what plugins to run.
This is the LDAP entry to work on.
This is the hash that was passed to the function calling the plugin.
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"; }
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!"; }
This changes the UID for a user.
The user to act on.
The GECOS to change this user to.
$pt->userGECOSchange({ user=>'someUser', gecos=>'whatever', }); if($pt->{error}){ print "Error!\n"; }
The shell to change this user to.
$pt->userShellChange({ user=>'someUser', shell=>'/bin/tcsh', }); if($pt->error){ print "Error!\n"; }
This changes the password for a user.
This is the user to act on.
This is the new password to set.
$pt->userSetPass({ user=>'someUser', pass=>'whatever', }); if($pt->{error}){ print "Error!\n"; }
The GID to change this user to. This GID must already exist.
$pt->userGIDchange({ user=>'someUser', gid=>'1234', }); if($pt->{error}){ print "Error!\n"; }
The UID to change this user to.
$pt->userUIDchange({ user=>'someUser', uid=>'1234', }); if($pt->{error}){ print "Error!\n"; }
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"; }
This is a internal function and should not be called.
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"; }
Could not read config.
Missing required variable.
Can't find a free UID.
Can't find a free GID.
No user name specified.
No group name specified.
UID is not numeric.
GID is not numeric.
User already exists.
Group already exists.
Connecting to LDAP failed.
Net::LDAP::posixGroup failed.
Failed to bind to the LDAP server.
The group does not exist.
The group does not exist in LDAP or under specified group base.
Failed to delete the group's entry.
The user does not exist.
The user does not exist in LDAP or under specified user base.
Adding the new entry failed.
The GID already exists.
Failed to create home.
Copying the skeleton to the home location failed.
Failed to chown the new home directory.
Failed to chmod the new home directory.
Failed to update a entry when removing a memberUid.
Failed to remove the users home directory.
Faild to fetch a list posixGroup objects.
No GID specified.
Failed to update the entry when changing the GID.
No UID specified.
Failed to update the entry when changing the UID.
Failed to fetch the user entry.
No GECOS specified.
Failed to update the entry when changing the GECOS.
No password specified.
Updating the password for the user failed.
Errored when fetching a list of users that may possibly need updated.
No LDAP object given.
$opts{do} has not been specified.
The specified selection of plugins to run does not exist.
Exectuting a plugin failed.
$opts{entry} is not defined.
$opts{entry} is not a Net::LDAP::Entry object.
$opts{ldap} is not a Net::LDAP object.
$returned{error} is set to true.
Calling the LDAP update function on the entry modified by the userSetPass plugin failed. The unix password has been set though.
No shell specified.
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
This is the DN to bind as.
This is the password for the bind DN.
This is the base for where the users are located.
This is the base where the groups are located.
This is the LDAP server to connect to. If the server is not specified, '127.0.0.1' is used.
This is the LDAP port to use. If the port is not specified, '389' is used.
This is the first UID to start checking for existing users at. The default is '1001'.
This is the first GID to start checking for existing groups at. The default is '1001'.
This is the default shell for a user. The default is '/bin/tcsh'.
The prototype for the home directory. %%USERNAME%% is replaced with the username. The default is '/home/%%USERNAME%%/'.
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'.
This is the numeric value the newly created home directory will be chmoded to. The default is '640'.
If home should be chmoded. The default value is '1', true.
If home should be chowned. The default value is '1', true.
If this is true, it the home directory for the user will be created. The default is '1'.
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'.
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'.
Wether or not it should try to do start_tls.
The verify mode for TLS. The default is 'none'.
The server may provide a certificate but it will not be checked - this may mean you are be connected to the wrong server.
Verify only when the server offers a certificate.
The server must provide a certificate, and it must be valid.
This is the SSL versions accepted.
'sslv2', 'sslv3', 'sslv2/3', or 'tlsv1' are the possible values. The default is 'tlsv1'.
This is a list of ciphers to accept. The string is in the standard OpenSSL format. The default value is 'ALL'.
This determines if it should try to remove the user's primary group after removing the user.
The default value is '1', true.
This determines if it should try to remove a user's home directory when deleting the user.
The default value is '0', false.
This determines if it should update the primary GIDs for users after groupGIDchange has been called.
A comma seperated list of plugins to run when addGroup is called.
A comma seperated list of plugins to run when addUser is called.
A comma seperated list of plugins to run when groupAddUser is called.
A comma seperated list of plugins to run when groupGIDchange is called.
A comma seperated list of plugins to run when groupRemoveUser is called.
A comma seperated list of plugins to run when userGECOSchange is called.
A comma seperated list of plugins to run when userSetPass is called.
A comma seperated list of plugins to run when userGIDchange is called.
A comma seperated list of plugins to run when userShellChange is called.
A comma seperated list of plugins to run when userUIDchange is called.
A comma seperated list of plugins to run when deleteUser is called.
A comma seperated list of plugins to run when deleteGroup is called.
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.
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;
Zane C. Bowers, <vvelox at vvelox.net>
<vvelox at vvelox.net>
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.
bug-plugtools at rt.cpan.org
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/
Copyright 2010 Zane C. Bowers, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Plugtools, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Plugtools
CPAN shell
perl -MCPAN -e shell install Plugtools
For more information on module installation, please visit the detailed CPAN module installation guide.