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.
do
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
1
Could not read config.
2
Missing required variable.
3
Can't find a free UID.
4
Can't find a free GID.
5
No user name specified.
6
No group name specified.
7
UID is not numeric.
8
GID is not numeric.
9
User already exists.
10
Group already exists.
11
Connecting to LDAP failed.
12
Net::LDAP::posixGroup failed.
13
Failed to bind to the LDAP server.
14
The group does not exist.
15
The group does not exist in LDAP or under specified group base.
16
Failed to delete the group's entry.
17
The user does not exist.
18
The user does not exist in LDAP or under specified user base.
19
Adding the new entry failed.
20
The GID already exists.
21
Failed to create home.
22
Copying the skeleton to the home location failed.
23
Failed to chown the new home directory.
24
Failed to chmod the new home directory.
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.
28
No GID specified.
29
Failed to update the entry when changing the GID.
30
No UID specified.
31
Failed to update the entry when changing the UID.
32
Failed to fetch the user entry.
33
No GECOS specified.
34
Failed to update the entry when changing the GECOS.
35
No password specified.
36
Updating the password for the user failed.
37
Errored when fetching a list of users that may possibly need updated.
38
No LDAP object given.
39
$opts{do} has not been specified.
40
The specified selection of plugins to run does not exist.
41
Exectuting a plugin failed.
42
$opts{entry} is not defined.
43
$opts{entry} is not a Net::LDAP::Entry object.
44
$opts{ldap} is not a Net::LDAP object.
45
$returned{error} is set to true.
46
Calling the LDAP update function on the entry modified by the userSetPass plugin failed. The unix password has been set though.
47
No shell specified.
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=barbind
This is the DN to bind as.
pass
This is the password for the bind DN.
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 PlugtoolsYou can also look for information at:
RT: CPAN's request tracker
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
ACKNOWLEDGEMENTS
COPYRIGHT & LICENSE
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.