NAME
GOto::LDAP - Support library for goto-* scripts to access LDAP
SYNOPSIS
use GOto::Common qw(:ldap);
use GOto::LDAP qw(ldap_get_object);
my $ldapinfo = goto_ldap_parse_config_ex(); #ref to hash
my ($ldapbase,$ldapuris) = ($ldapinfo->{"LDAP_BASE"}, $ldapinfo->{"LDAP_URIS"});
my $ldap = Net::LDAP->new( $ldapuris, timeout => $timeout ) or die;
$ldap->bind() ; # anonymous bind
# list context
my @results = ldap_get_object(ldap => $ldap,
basedn => $ldapbase,
user => $user,
timeout => $timeout,
filter => $filter,
debug => $debug,
objectClass => $objectClass,
cnou => $cn,
subquery => $subquery,
sublevel => $sublevel,
subconflict => $subconflict,
attributeSelectionRegexes => \@attributeSelectionRegexes,
enctrigger => $enctrigger,
format => $format,
dups => $dups,
mergeResults => $mergeResults
);
@results or die;
# scalar context
my $result = ldap_get_object(...);
$result or die;
DESCRIPTION of "ldap_get_object"
"ldap_get_object()" reads information about an object (usually a user,
but can also be a workstation, a POSIX group,...) from LDAP.
"ldap_get_object()" understands gosaGroupOfNames and posixGroups and
will not only return properties of the queried object itself but also
properties inherited from groups of both types.
PARAMETERS
ldap
An object of type Net::LDAP that is already bound. Required.
basedn
The base DN to use for all searches. Required.
user/cnou and objectClass
You must pass either "user" or "cnou". If you pass "user",
"objectClass" is ignored and "ldap_get_object()" will search for an
object with "objectClass=posixAccount" and "uid" equal to the value
passed as "user".
If you pass "cnou", then you must also pass "objectClass" and
"ldap_get_object()" will search for an object with the given
"objectClass" and a "cn" equal to the value passed as "cnou". If no
such object is found, it will attempt to find an object with the
given "objectClass" and "ou" equal to the value of "cnou".
attributeSelectionRegexes and CONFLICT RESOLUTION
A reference to a an array of regular expressions (as strings) that
select the attributes to be returned and determines how to proceed
in case there are multiple sources for an attribute (e.g. the
user’s posixAccount node and a posixGroup the user is a member of).
Each regex selects all attributes with matching names.
If the regex starts with the character "@" (which is ignored for
the matching), then attribute values from different sources will be
merged (i.e. the result will include all values).
If attributeRegex does NOT start with "@", then an attribute from
the queried object’s own node beats a posix group, which beats an
object group (=gosaGroupOfNames) that includes the object directly
which beats an object group that contains a posix group containing
the object. Object groups containing other object groups are not
supported by GOsa, so this case cannot occur.
If 2 sources with the same precedence (e.g. 2 posix groups) provide
an attribute of the same name, selected by a regex that doesn not
start with "@", then a WARNING is signalled and the program picks
one of the conflicting attributes.
If multiple attribute regexes match the same attribute, the 1st
matching attribute regex’s presence or absence of "@" determines
conflict resolution.
Matching is always performed against the complete attribute name as
if the regex had been enclosed in "^...$", i.e. an attribute regex
"name" will NOT match an attribute called "surname". Neither will
the regex "sur".
Matching is always performed case-insensitive.
If the parameter "attributeSelectionRegexes" is not passed, it
defaults to "@.*".
mergeResults
If "mergeResults" is "false" and "ldap_get_object()" is evaluated
in list context, then it will return a list of Net::LDAP::Entry
objects where each object represents the attributes on a given
precedence level. The first entry gives the attributes that come
from the own node, i.e. those with the highest precedence.
Attributes selected with a non-"@" regex, i.e. those for which only
one source is permitted, are always found in the first entry and
only there. For these attributes all conflicting values from lower
precedence levels are always discarded, so "mergeResults=false"
only makes sense when requesting merged attributes via "@".
If "mergeResults" is "true" (the default) or if "ldap_get_object()"
is evaluated in scalar context, then only one Net::LDAP::Entry will
be returned that contains all of the requested attributes.
dups
Net::LDAP::Entry does not perform duplicate removal on its
attribute value lists by default. If "dups=true" (the default),
the results returned from "ldap_get_object()" may contain
attributes that contain duplicate entries. If this would confuse
your code, pass "dups=false" and duplicate values will be
eliminated (at the cost of a few CPU cycles).
timeout
If "timeout" is passed, LDAP requests will use a timeout of this
number of seconds. Note that this does not mean that
"ldap_get_object" will finish within this time limit, since several
LDAP requests may be involved.
Default timeout is 10s.
filter
"filter" is an LDAP-Expression that will be ANDed with all
user/object/group searches done by this program.
Use this to filter by "gosaUnitTag".
subquery
The "subquery" parameter is an LDAP filter such as
"objectClass=gotoMenuItem". For the subtrees rooted at the object’s
own node and at all of its containing groups’ nodes, an LDAP query
using this filter will be done. The attributes of all of the
objects resulting from these queries will be treated as if they
were attributes of the node at which the search was rooted. The
names of these pseudo-attributes have the form "foo/bar/attr".
sublevel
"sublevel" specifies the maximum number of slashes the pseudo-
attribute names will contain. If the complete name of a pseudo-
attribute has more slashes than the given number, the name will be
shortened to the longest suffix that contains this many slashes.
Specifying a "sublevel" of 0 will effectively merge all subquery
nodes with the user/object/group node so that in the end result
their attributes are indistinguishable from those of the
user/object/group node.
Default "sublevel" is 9999.
Note: attribute regex matching is performed on the full name with
all slashes.
subconflict
"subconflict" is a number that determines when 2 pseudo-attributes
are treated as being in conflict with each other. 2 pseudo-
attributes are treated as conflicting if the results of removing
the shortest suffixes containing "subconflict" slashes from their
names (shortened according to "sublevel") are identical. E.g. with
"subconflict=0" the pseudo-attributes "foo/bar" and "foo/zoo" are
not conflicting, whereas with "subconflict=1" they are. Default
"subconflict" is 1.
debug
If "debug" is "true", then lots of debug output (mostly all of the
nodes considered in constructing the result) is printed to stdout.
enctrigger
This parameter is only relevant when "debug" is "true". It affects
the way, attribute values are printed. If "enctrigger" is passed,
it is interpreted as a regular expression and all DNs and attribute
values will be tested against this regex. Whenever a value matches,
it will be output base64 encoded. Matching is performed case-
sensitive and unless ^ and $ are used in the regex, matching
substrings are enough to trigger encoding.
If no "enctrigger" is specified, the default "[\x00-\x1f]" is used
(i.e. base64 encoding will be used whenever a value contains a
control character). If you pass "enctrigger=none", encoding will
be completely disabled.
format
This parameter is only relevant when "debug" is "true". It affects
the way, attribute values are printed. Format "a:v" means to print
"attributeName: value" pairs. Format "v" means to print the values
only.