start page | rating of books | rating of authors | reviews | copyrights

Book HomeJava and XSLTSearch this book

19.4. Net::LDAP Methods

Net::LDAP implements the following methods:

new (host [, %options ])
new( ) creates a new Net::LDAP object and opens a connection to host. %options include:

port
Port to connect to on the remote server.

timeout
The maximum time that Net::LDAP will take to connect to a host. The default is 120 seconds.

debug
Shows details of the conversion between Net::LDAP and the directory server.

async
Performs asynchronous entry retrieval so that search results are returned to the client as they are identified:

$ldap = Net::LDAP->new('ldap.my.domain', async => 1);
onerror
If set to true, and if async is also true, then Net::LDAP will check for errors on all methods. If an error exists in the resulting data, then one of the following actions will be taken: die( ), warn( ), undef.

CODEREF
Calls the given coderef in a scalar context with the result message as the argument.

version( )
Sets the version of the LDAP protocol to use. Values are LDAPv2 (default) and LDAPv3.

bind(dn [, %options ])
Binds to the server that's contained in the connection handle. dn is the DN to bind as. You'll end up binding anonymously if you call bind( ) without any arguments.

As for %options, you should give no more than one of the following:

noauth
Do not attempt to authenticate at all.

anonymous
Binds without any password; the value passed with this option is ignored. This is the default if no arguments are given.

password
Binds with the given password.

sasl
Binds using an SASL mechanism. The argument given should be a sub-class of Authen::SASL.

my $dn = 'cn=Directory Manager';
my $password = 'adminpass';
my $sasl = Authn::SASL::stuff::here;
$ldap->bind($dn, sasl => $sasl, version => 3);
unbind
Does not take any parameters and unbinds the connection from the server. You will probably need to call bind( ) again if you wish to reconnect to the LDAP server.

$ldap->unbind;
add ( dn [, %options ] )
Adds an entry to the directory. dn can be either a Net::LDAP::Entry object or a string that represents the DN.

attrs
A reference to a list of attribute/value pairs. These attribute/value pairs correspond to the attributes of an entry in the directory. Each attribute can have multiple values. attrs is not used if dn is an existing Net::LDAP::Entry object. For example:

$ldap->add($dn,
           attrs => [
               'uid'        => 'nvp',
               'cn'         => ['Nathan Patwardhan', 'Enrico Pallazo'],
               'gecos'      => 'Nathan Patwardhan',
               'loginShell' => '/usr/bin/bash'
           ]
);
delete(dn [, %options ])
Deletes dn from the server. dn may be a string that represents the DN or a Net::LDAP::Entry object. For example:

my $dn = q[uid=nvp,ou=People,o=my.domain];
$ldap->delete($dn);
moddn(dn, %options)
Modifies dn. dnmay be a string or a Net::LDAP::Entry object.

newrdn
A new RDN to assign to dn.

deleteoldrdn
True if the existing RDN will be deleted.

newsuperior
If given, this value should be the dn of the new superior for dn.

$ldap->moddn($dn, newrdn => 'cn=Nate Patwardhan');
modify(dn, %options)
Modifies the contents of dn. dn may be a string or a Net::LDAP::Entry object.

add
Should be a reference to a HASH. HASH is comprised of the attributes to add, and the values may be a string or a reference to a list of values.

delete
A reference to ARRAY that contains attributes to delete, or a reference to a HASH, if only specific values should be deleted. If the values for any attribute in HASH are references to an empty ARRAY, then all instances of the attribute will be deleted.

replace
Works like add, but will replace any of the existing attributes.

changes
An alternative to add, delete, and replace, in which the whole operation can be given in a single argument. The argument should be a reference to an ARRAY.

Values in the ARRAY are used in pairs; the first is the operation add, delete, or replace, and the second is a reference to an ARRAY of attribute values.

The attribute value list is also used in pairs. The first value in each pair is the attribute name, and the second is a reference to a list of values.

Use this form if you want to control the order in which the operations will be performed:

my $dn = q[uid=nvp,ou=People,o=my.domain];

$ldap->modify($dn, add => { sn => 'Patwardhan' } );
$ldap->modify($dn, delete => { 'weight' => '175' });
$ldap->modify($dn, replace => { 'loginShell' => '/usr/bin/tcsh' });
$ldap->modify( $dn,
   changes => [
     add     => [ sn => 'Patwardhan' ],
     delete  => [ faxNumber => []],
     delete  => [ weight => ['175']],
     replace => [ loginShell => '/usr/bin/tcsh']
   ]
);
search(@options)
Requests that an LDAP server perform a search and can read attributes from a single entry, entries immediately below a particular entry, or a whole subtree of entries. The result is an object of the class Net::LDAP::Search.

base
The DN that is the base object entry relative to the search that will be performed.

scope
By default, the search is performed on the whole tree below the specified base object. This may be changed by specifying a scope parameter with one of the following values:

base
Searches only the base object.

one
Searches the entries immediately below the base object.

sub
Searches the whole tree below the base object. This is the default.

deref
By default, aliases are dereferenced to locate the base object for the search, but not when searching subordinates of the base object. This may be changed by specifying a deref parameter with one of the following values:

never
Do not dereference aliases in searching or in locating the base object of the search.

search
Dereferences aliases in subordinates of the base object in searching, but not in locating the base object of the search.

find
Dereferences aliases in locating the base object of the search, but not when searching subordinates of the base object. This is the default.

always
Dereferences aliases both in searching and in locating the base object of the search.

sizelimit
Restricts the maximum number of entries to be returned as a result of the search. A value of 0, which is the default, means that no restriction is requested. Servers may enforce a maximum number of entries to return.

timelimit
Restricts the maximum time (in seconds) allowed for a search. A value of 0, which is the default, means that no timelimit will be requested.

typesonly
Indicates whether search results should contain both attribute types and values, or just attribute types. Setting this parameter to true causes only attribute types (no values) to be returned. Setting this field to false causes both attribute types and values to be returned. This is the default.

filter
Defines the conditions an entry in the directory must meet in order for it to be returned by the search. This may be a string or a Net object. See the Net::LDAP::Filter manpage for a further description of the filter format.

attrs
A reference to a list of attributes to be returned for each entry that matches the search filter.

If not specified, then the server will return the attributes that are specified as accessible by default given your bind credentials.

Certain additional attributes, such as createtimestamp, and other operational attributes may also be available for the asking:

$ldap->search( ... , attrs => ['createtimestamp'] , ... );

To retrieve the default attributes and additional ones, use "*":

my $base_dn = q[o=my.domain];
$mesg = $ldap->search(
  base   => $base_dn,
  scope  => 'sub',
  filter => '(|(objectclass=rfc822mailgroup)(sn=Patwardhan))'
);

Net::LDAP::LDIF->new(\*STDOUT,"w")->write($mesg->entries);
abandon(id [, %options ] )
Requires that a server abandons a request. id may be passed first, or as part of %options, and may be a number or a Net::LDAP::Message object that's returned from a previous method call.

$mesg = $ldap->search(@search_args);
$ldap->abandon($mesg); # This could be written as $mesg->abandon
compare(dn, %options)
Performs a comparison on the server. dn is the DN on which the comparison will be performed. dn may be a string or Net::LDAP::Entry object.

attr
The name of the attribute to compare.

value
The value to compare with.

my $dn = q[uid=nvp,ou=People,o=my.domain];
$ldap->compare($dn,
    attr  => 'cn',
    value => 'Nathan Patwardhan'
);
start_tls([%options])
Converts the connection to use Transport Layer Security (TLS), which provides an encrypted connection, if available. Bear in mind that TLS is supported only under LDAPv3. %options is a set of key/value pairs that describe how to configure the security of the connection:

verify
Indicates how to verify the server's certificate. Its values can be none (the server may provide a certificate, but it will not be checked—this may mean you are connected to the wrong server), optional (verifies if the server offers a certificate), or require (the server must provide a certificate, and it must be valid). If you set verify to optional or require, you must also set either cafile or capath. The most secure option is require.

sslversion
Defines the version of the SSL/TLS protocol to use. Defaults to tlsv1; other possible values are sslv2, sslv3, and sslv2/3.

ciphers
Specifies which subset of cipher suites is permissible for this connection, using the standard OpenSSL string format. The default value for ciphers is ALL, which permits all ciphers, even those that don't encrypt!

clientcert
clientkey
If you want to use the client to offer a certificate to the server for SSL authentication (which is not the same as for the LDAP Bind operation), then set clientcert to the user's certificate file and clientkey to the user's private key file. These files must be in PEM format.

capath
cafile
When verifying the server's certificate, set either capath to the pathname of the directory containing CA certificates or cafile to the filename containing the certificate of the CA who signed the server's certificate. These certificates must all be in PEM format.

The directory in capath must contain certificates named using the hash value of themselves. To generate these names, use OpenSSL in Unix, as follows:

ln -s cacert.pem 'openssl x509 -hash -noout < cacert.pem'.0

(assuming that the certificate of the CA is in cacert.pem).

cipher
Returns the cipher mode being used by the connection in the string format used by OpenSSL.

certificate
Returns an X509_Certificate object containing the server's certificate. For example, to get the subject name (in a peculiar OpenSSL-specific format, different from RFC 1779 and RFC 2253) from the server's certificate, do the following:

print "Subject DN: " . $ldaps->certificate->subject_name . "\n";
version
Returns the version of the LDAP protocol that is being used.



Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.