Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  NET::LDAP::EXPRESS (3)

.ds Aq ’


Net::LDAP::Express - Simplified interface for Net::LDAP



With version 0.10 the return value for the error method has slightly changed; on no-error condition (error code 0) it returns a null string, and not undef any more. Code that simply checked for boolean true/false value will continue to work as expected, but code that relied on undef and the defined function won’t! <B>Please let me know if this behaviour breaks any existing application!B>. Thanks.


  use Net::LDAP::Express;

  eval {
    my $ldap =
      Net::LDAP::Express->new(host => localhost,
                              bindDN => cn=admin,ou=People,dc=me,
                              bindpw => secret,
                              base   => ou=People,dc=me,
                              searchattrs => [qw(cn uid loginname)],
                              %parms) ; # params for Net::LDAP::new
  } ;

  if ($@) {
    die "Cant connect to ldap server: $@" ;

  my $filter = (|(loginname=~bronto)(|(cn=~bronto)(uid=~bronto))) ;
  my $entries ;
  # These all return the same array of Net::LDAP::Entry objects
  $entries = $ldap->search(filter => $filter) ; # uses new()s base
  $entries = $ldap->search(base   => ou=People,dc=me,
                           filter => $filter) ;
  $entries = $ldap->simplesearch(bronto) ; # uses new()s searchattrs

  # Now elaborate results:
  foreach my $entry (@$entries) {
    modify_something_in_this($entry) ;

  # You often want to update a set of entries
  foreach my $entry (@$entries) {
    die "Error updating entry" unless defined $ldap->update($entry) ;

  # but I think youll prefer this way:
  my $result = $ldap->update(@$entries) ;
  unless (@$result == @$entries) {
    print "Error updating entries: ",$ldap->error,
          "; code ",$ldap->errcode,".\n\n" ;

  # Add an entry, or an array of them, works as above:
  die $ldap->error unless $ldap->add_many(@some_other_entries) ;

  # rename an entry: sometimes you simply want to change a name
  # and nothing else...
  $ldap->rename($entry,$newrdn) ;

  # Ask for just a few attributes, sort results
  $ldap = Net::LDAP::Express->new(host        => $server,
                                  port        => $port,
                                  base        => $base,
                                  bindDN      => $binddn,
                                  bindpw      => $bindpw,
                                  onlyattrs   => \@only,
                                  sort_by     => \@sortby,
                                  searchattrs => \@search) ;
  my $entries = $ldap->simplesearch(person) ;


Net::LDAP::Express is an alternative interface to the fantastic Graham Barr’s Net::LDAP, that simplifies the tasks of adding and deleting multiple entries, renaming them, or searching entries residing in a common subtree.

Net::LDAP is a great module for working with directory servers, but it’s a bit overkill when you want to do simple short scripts or have big programs that always do the same job again and again, say: open an authenticated connection to a directory server, search entries against the same attributes each time and in the same way (e.g.: approx search against the three attributes cn, uid and loginname). With Net::LDAP this would mean:
o connect to the directory server using new();
o authenticate with bind() ;
o compose a search filter, and pass it to search(), along with the base subtree;
o perform the search getting a Net::LDAP::Search object;
o verify that the search was successful using the code() or is_error() method on the search object;
o if the search was successful, extract the entries from the Search object, for example with entries or shift_entry.
With Net::LDAP::Express this is done with:
o connect, authenticate, define default search subtree and simple-search attributes with the new() method;
o pass the simplesearch method a search string to be matched against the attributes defined with searchattrs in new() and check the return value: if it was successful you have a reference to an array of Net::LDAP::Entry objects, if it was unsuccessful you get undef, and you can check what the error was with the error() method (or the error code with errcode) ;


new(%parms) Creates a Net::LDAP::Express object. Accepts all the parameters that are legal to Net::LDAP::new but the directory server name/address is specified via the host parameter. Specific Net::LDAP::Express parameters are therefore:
host the name or IP address of the directory server we are connecting to. Mandatory.
port the port to connect to; if omitted, the 389 will be used. 389 is the LDAP standard port.
bindDN bind DN in case of authenticated bind
bindpw bind password in case of authenticated bind
base base subtree for searches. Mandatory.
searchattrs attributes to use for simple searches (see the simplesearch method);
searchbool boolean operator in case that more than one attribute is specified with searchattrs; default is ’|’ (boolean or); allowed boolean operators are | and &.
searchmatch By default, an ’approx’ search is performed by simplesearch(); for those directory servers that doesn’t support the ~= operator it is possible to request a substring search specifying the value ’substr’ for the searchmatch parameter. Alternatively, if this is set to ’exact’ then an exact search will be done - useful when fields are not indexed for substring searching.
searchextras A list of attributes that should be returned in addition of the default ones.
onlyattrs At the opposite of searchextras: if you need just a few attributes to be returned for each entry, you can specify them here. Note that it doesn’t make much sense to include both searchextras and onlyattrs.
sort_by If you specify this parameter with a list of attributes, the simplesearch method will return the entries sorted by the attributes given. Note that if you also specify onlyattrs and there are attributes in sort_by that are not in onlyattrs, they will be added to allow the Net::LDAP::Search::sorted method to work.


All Net::LDAP methods are supported via inheritance. Method specific in Net::LDAP::Express or that override inherited methods are documented below.
search search works exactly as Net::LDAP::search(), with a few changes:
o it takes advantage of the defaults set with new(): uses new()’s base parameter if you don’t specify another base, and adds searchextras to default attributes, or uses onlyattrs, unless you specify an attrs parameter.
o if you pass it an odd number of parameters, then the first is considered as a query string, that is used internally yo build a search filter; anyway, if you specify a search filter with the filter parameter the query string is discarded

search() returns a Net::LDAP::Search object, thus mantaining an almost complete compatibility with the parent class interface.


add_many Takes one or more Net::LDAP::Entry objects, returns a reference to an array of Net::LDAP::Entry objects that successfully made it on the directory server. You can check if every entry has been added by comparing the length of the input list against the length of the output list. Use the error and/or errorcode methods to see what went wrong.
delete_many Works the same way as add_many, but it deletes entries instead :-)
rename($entry,$newrdn) Renames an entry; $entry can be a Net::LDAP::Entry or a DN, $newrdn is a new value for the RDN. Returns $entry for success, undef on failure.
update(@entries) update takes a list of Net::LDAP::Entry objects as arguments and commits changes on the directory server. Returns a reference to an array of updated entries.

<B>NOTE:B> if you want to modify an entry, say $e, remember to call $e->changetype(modify) on it <B>beforeB> doing any changes; the defined changetype at object creation is add at the moment, which results in update trying to create new entries. This could be addressed by Net::LDAP::Express in the future, maybe.

simplesearch($searchstring) Searches entries using the new()’s search* and base parameters. Takes a search string as argument. Returns a reference to an array of entries on success, undef on error.
error Returns last error’s name
errcode Returns last error’s code


Marco Marongiu, <>

sort_by feature kindly suggested by John Woodell

Original patch for exact matching (code and documentation) was kindly contributed by Gordon Lack.


Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 EXPRESS (3) 2014-06-28

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.