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
.
dn
may be a string or a
Net::LDAP::Entry object.
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.
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 . " ";
version
Returns the version of the LDAP protocol that is being used.
18.217.254.118