ldaputils -- Basic Ldap functions for adding, modifying and removing objects
use ldaputils;
$ldap = ldaputils->new(configfile => '/path/to/configfile',
ldap_bind_user => 'ldap_bind_user',
ldap_bind_secret => 'ldap_bind_secret');
ldaputils is collection of basic functions to add, remove and modify ldap objects.
The basic idea for writing this module was to get some basic functions which simplify implementing scripts to deal with the various LDAP objects.
The difficulty was that different LDAP object classes differ in number, names and type of attributes. Therefore any information about this classes is kept in a separate schema file. See CONFIGURATION FILES below.
Some basic configuration stuff is kept in a separate configuration file. See CONFIGURATION FILES below.
Constructor to create a new ldaputils object. Parameters are given in form of a hash as key - value pairs.
Full or relative path name of the config file to be read
Username to use for the ldap bind. (username _not_ dn)
Password to use for ldap bind
Example
$ldaputils = new ldaputils(
configfile=>'/usr/local/ldap/etc/ldaputils.conf );
Performs an ldap search and returns all objects found. The results are returned as reference to a result hash. Keys in the result hash are the values found in the attribute named by 'keyattr'. Every value in the result hash is a reference to hash containing a single object. Keys are the attribute names from the 'attr' array. Every entry in this hash is a reference to an array containing all the values for one attribute.
Got it? ;-)
Better take a look at the example below.
Parameters are given in form of a hash as key - value pairs.
Filterstring to use for the ldap search
Object's attribute to use as a primary key in the result hash
Refernce to an array containing the attributes to retrieve for all found ldap objects
Example Call get_objects as
$result = $ldaputils ->
get_objects( filter => ``(objectClass=sambaAccount)'',
keyattr => ntUid, attr => [rid,smbHome,profile]);
The filter (objectClass=sambaAccount) should return several LDAP objects. Eg: One entry for 'Administrator' and one entry for 'nobody'.
'ntUid' is given as 'keyattr' and the values found in the attribute 'ntUid' of the objects 'Administrator' and 'nobody' will be used as primary key in the result hash.
Therefore you can access these two entries by means of:
$$result{Administrator} and $$result{nobody}
The $$result is necessary as $result is only a
reference to the result hash. You can now access the additional attributes
fetched by means of: $$result{Administrator}{rid} or
$$result{nobody}{profile}
As every attribute might contain multiple values (think of the sambaMember attribute) the above are refernces to arrays: $$result{Administrator}{rid}[0] should contain the Administrators rid: '1F4'
Sometimes you may want to access all the keys in the result hash. Consider something like:
foreach $user ( @all_found_users ) {...}
Therefore you have to use a syntax like this:
foreach $user ( keys %{$result} ) {...}
or even more complicated if you want to run something like:
foreach $attribute ( @all_found_attributes )
{...}
use
foreach $attribute ( keys %{${$result}{nobody}} ) {...}
Gets exaktly one ldap object, can be use to get objects of whom you now they are unique. Think of users, groups, ...
The object_type used should be one which is defined in the schema file, as get_object calls get_objects with a filter build of the objectclass taken from the schemafile and an additional filter build of the given attr_name and attr_value. If more or less than one object is found, an empty result is returned. Parameter hash:
Object type from the schema definitions file
Attribute name to be used as search criteria
Attribute value to be used as search criteria
Example
$obj_handle = $ldaputils ->
get_object( object_type => 'user', attr_name => 'uid',
attr_value => 'root' );
print $$obj_handle{cn};
Similar to get_object but you only have to supply object_type and unique_id as parameters. The object_type used should be one which is defined in the schema file, as get calls get_object. If more or less than one object is found, an empty result is returned. Parameter hash:
Object type from the schema definitions file
Attribute name to be used as search criteria
Example
$obj_handle = $ldaputils -> get(
object_type => 'user', unique_id => 'root' );
print $$obj_handle{cn};
Checks if the specified object exists in the LDAP database. Calls get_object, checks the result and return true or false. Parameter hash:
Object type from the schema definitions file
Attribute name to be used as search criteria
Attribute value to be used as search criteria
Example
if ( $ldaputils -> object_exists( object_type
=> 'user', attr_name => 'uid', attr_value => 'root' ) ) {...}
Similar to object_exists but you only have to supply object_type and unique_id as parameters.
Object type from the schema definitions file
Attribute name to be used as search criteria
Example
if ( $ldaputils -> exists( object_type =>
'user', unique_id => 'root' ) ) {...}
Creates a new object hash. Creates an empty object hash, sets all the argument values given on the command line. Normally it should be easier to use add_object instead, but sometimes it might be necessary to modify the newly created object, before adding it to the LDAP Directory. Parameter hash:
Type of the object to fill with the commandline args (schema file)
Attribute value of the unique_id field (eg: name)
Reference to a hash containing the commandline arguments
Example
$new_obj_handle = $ldaputils ->
get_new_object( object_type => 'user', unique_id =>
'root', cmdl_args => {uid => ``2087'', homeDirectory =>
``/home/newuser''} );
Creates a new LDAP object. Creates an empty object, sets all the commandline argument values and adds the object to the LDAP directory. Gets the objectclass and unique_id fieldname from the schemafile. Parameter hash:
Type of the object to create
Attribute value of the unique_id field
Reference to a hash containing the commandline arguments
Example
$ldaputils -> add_object( object_type =>
'user', unique_id => 'newuser', cmdl_args => \%args );
Modifies an LDAP object. Gets an existing LDAP object, sets all the commandline argument values and modifies the LDAP object. Gets the objectclass and unique_id fieldname from the schemafile. Parameter hash:
Type of the LDAP object to modify
Attribute value of the unique_id field
Reference to a hash containing the commandline arguments
Example
$ldaputils -> mod_object( object_type =>
'user', unique_id => 'newuser', cmdl_args => \%args );
Compares the attributes from an existing LDAP object to the given commandline arguments. Gets the objectclass and unique_id fieldname from the schemafile. Parameter hash:
Type of the object in LDAP directory to compare to commandline arguments
Attribute value of the unique_id field
Reference to a hash containing the commandline arguments
Example
if ( $ldaputils -> compare_object( object_type
=> 'user', unique_id => 'newuser', cmdl_args => \%args ) ) {...}
Deletes an ldap object. Gets the objectclass and unique_id fieldname from the schemafile. Parameter hash:
Type of the object to delete
Attribute value of the unique_id field
Reference to a hash containing the commandline arguments keys are the argument names.
Example
$ldaputils -> del_object( object_type =>
'user', unique_id => 'newuser' );
Gets the distinguished name for an existing object Gets the objectclass and unique_id fieldname from the schemafile. Parameter hash:
Type of the object to fill with the commandline args
Attribute value of the unique_id field to fetch the dn for
Example
$dn = $ldaputils ->
get_dn( object_type => 'user', unique_id => 'newuser' );
Creates the distinguished name for a new object Gets the objectclass and unique_id fieldname from the schemafile. Parameter hash:
Type of the object to fill with the commandline args
Attribute value of the unique_id field to fetch the dn for
Reference to a hash containing the commandline arguments keys are the argument names.
Example
$newdn = $ldaputils ->
get_new_dn( object_type => 'user', unique_id =>
'newuser', cmdl_args => \%args );
Gets the objectClass for an existing object. Gets the objectclass and unique_id fieldname from the schemafile.
Type of the object to fill with the commandline args
Attribute value of the unique_id field to fetch the dn for
Example
$objclass = $ldaputils ->
get_objectclass( object_type => 'user', unique_id =>
'root' );
Creates the objectClass for a new object Gets the objectclass and unique_id fieldname from the schemafile. Parameter hash:
Type of the object to fill with the commandline args
Example
$newobjclass = $ldaputils ->
get_new_objectclass( object_type => 'user' );
Gets the next free account id. Start from the sys_accout_rid value in the configfile and searches for any unused uid/rid pair. Returns the decimal id.
Example
$free_id = $ldaputils ->
get_free_account_id();
Checks if the next free account id in the sambaConfig entry has to be increased.
Example
$ldaputils -> set_free_account_id( id =>
$free_id );
adds an object to the ldap database Parameter hash:
Distinguished name of the object to add
Reference to a hash. keys are the attribute names of the LDAP object, hash values are the attribute values.
Modifies an object in the ldap database Parameter hash:
Distinguished name of the object to modify
Reference to a hash. keys are the attribute names of the LDAP object, hash values are the attribute values.
Deletes an object from the ldap database Parameter hash:
Distinguished name of the object to delete
The full path to the configuration file has to be passed to the CONSTRUCTOR. The configuration file contains some basic information needed by the ldaputils module. Below you find an example configuration file with explanations for each parameter.
Hostname or IP-address of the LDAP Server.
Distinguished name of the LDAP base.
Full path to the schema file. See CONFIGURATION FILES below.
Full path to the log file. If no log filename is supplied, no logging is done
Full path to the mkntpwd utility.
Allow password files to be used. with sys_auth_allow_pwdfiles = 0 the user is prompted for a password to use for the LDAP bind. With sys_auth_allow_pwdfiles = 1 the password is read from the file ~/.ldaputils if it exists (see below).
Name of the password file to use.
Creates crypt or md5 passwords.
Debug Level between 0 and 10.
Add and delete cyrus mailbox with useraccounts
Full path to the cyradm binary
Cyrus Imap Server
Cyrus Admin user
The following options have to be present but you should never need to modify this parameters.
sys_ldap_bind_objecttype = user
sys_cmdl_ou = ou
sys_nextrid_filterclass = SambaConfig
sys_nextrid_filterattr = id
sys_nextrid_filtervalue = root
sys_nextrid_attr = nextRid
The schema file contains all information about the object classes used by ldaputils.
For every object class it defines the attribute names, their default values
and the commandline switches which should be evaluated to handle the
attributes. Let's take a look at an example schema file:
{
user => {
default_ou => "ou=People,dc=pingworks,dc=de",
name_attr => [ "uid", "cn", "ntUid" ],
unique_id => "uid",
account_id => {uidNumber=>"dec", rid=>"hex"},
objectclass => [ "posixAccount", "shadowAccount" ],
defaults => {
cn => "",
sn => "",
uid => "",
uidNumber => "",
gidNumber => "100",
homeDirectory => "/home/",
userPassword => ""
},
cmdl => {
cn => "",
sn => "",
uid => "",
uidNumber => "uid",
gidNumber => "group",
homeDirectory => "homeDir",
userPassword => "password"
}
},
group => {
[..]
}
};
This schema file defines an object class user (and group).
The default ou where new user objects will be added to the LDAP directory is defined as ou=People,dc=pingworks,dc=de.
name_attr defines all attributes which will automatically be set to the objects name on creation.
unique_id defines the attribute which is used for all functions which take the unique_id argument.
objectclass defines the value of the objectClass attribute on new user objects.
Eg: get(object_type=``user'', unique_id=``root'') will search
for LDAP objects with an objectclass of 'posixAccount' and a 'uid' of
'root'.
The default section defines the default values set for new user objects.
The cmdl section defines which commandline switches are evaluated on creation.