1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
|
<HTML>
<HEAD>
<TITLE>DBD::LDAP - Perl extension for DBI, providing an SQL/Perl DBI interface
to LDAP databases. LDAP stands for the "Lightweight Directory Access
Protocol". For more information, see: http://www.ogre.com/ldap/docs.html</TITLE>
<LINK REV="made" HREF="mailto:flepied@debris.mandrakesoft.com">
</HEAD>
<BODY>
<CENTER>
</CENTER>
<A NAME="__index__"></A>
<!-- INDEX BEGIN -->
<UL>
<LI><A HREF="#name">NAME</A></LI>
<LI><A HREF="#author">AUTHOR</A></LI>
<LI><A HREF="#prerequisites">PREREQUISITES</A></LI>
<LI><A HREF="#synopsis">SYNOPSIS</A></LI>
<LI><A HREF="#description">DESCRIPTION</A></LI>
<LI><A HREF="#installation">INSTALLATION</A></LI>
<LI><A HREF="#getting started:">GETTING STARTED:</A></LI>
<LI><A HREF="#inserting, fetching and modifying data">INSERTING, FETCHING AND MODIFYING DATA</A></LI>
<LI><A HREF="#metadata">METADATA</A></LI>
<LI><A HREF="#other supporting utilities">OTHER SUPPORTING UTILITIES</A></LI>
<LI><A HREF="#restrictions">RESTRICTIONS</A></LI>
<LI><A HREF="#todo">TODO</A></LI>
<LI><A HREF="#known bugs">KNOWN BUGS</A></LI>
</UL>
<!-- INDEX END -->
<HR>
<P>
<H1><A NAME="name">NAME</A></H1>
<PRE>
DBD::LDAP - Perl extension for DBI, providing an SQL/Perl DBI interface
to LDAP databases. LDAP stands for the "Lightweight Directory Access
Protocol". For more information, see: <A HREF="http://www.ogre.com/ldap/docs.html">http://www.ogre.com/ldap/docs.html</A></PRE>
<P>
<HR>
<H1><A NAME="author">AUTHOR</A></H1>
<PRE>
This module is Copyright (C) 2000-2004 by</PRE>
<PRE>
Jim Turner
</PRE>
<PRE>
Email: <A "mailto:turnerjw@wwol.com">turnerjw@wwol.com</A></PRE>
<PRE>
All rights reserved Without Prejudice.</PRE>
<PRE>
You may distribute this module under the terms of either the GNU General
Public License or the Artistic License, as specified in the Perl README
file.</PRE>
<P>
<HR>
<H1><A NAME="prerequisites">PREREQUISITES</A></H1>
<PRE>
Convert::ANS1 (required by Net::LDAP)
Net::LDAP
DBI
- an LDAP database to connect to.</PRE>
<P>
<HR>
<H1><A NAME="synopsis">SYNOPSIS</A></H1>
<PRE>
use DBI;
$dbh = DBI->connect("DBI:LDAP:ldapdb",'user','password') #USER LOGIN.
or die "Cannot connect as user: " . $DBI::errstr;</PRE>
<PRE>
$dbh = DBI->connect("DBI:LDAP:ldapdb") #ANONYMOUS LOGIN (Read-only).
or die "Cannot connect as guest (readonly): " . $DBI::errstr;</PRE>
<PRE>
$sth = $dbh->prepare("select * from people where (cn like 'Smith%')")
or die "Cannot prepare: " . $dbh->errstr();
$sth->execute() or die "Cannot execute: " . $sth->errstr();
while ((@results) = $sth->fetchrow_array)
{
print "--------------------------------------------------------\n";
++$cnt;
while (@results)
{
print "------>".join('|',split(/\0/, shift(@results)))."\n";
}
}
$sth->finish();
$dbh->disconnect();</PRE>
<P>
<HR>
<H1><A NAME="description">DESCRIPTION</A></H1>
<P>DBD::LDAP is a DBI extension module adding an SQL database interface to
standard LDAP databases to Perl's database-independent database interface.
You will need access to an existing LDAP database or set up your own using
an LDAP server, ie. ``OpenLDAP'', see (http://www.openldap.org).</P>
<P>JLdap.pm is included in this module as a separate file, and is required.</P>
<P>The main advantage of DBD::LDAP is the ability to query LDAP databases via
standard SQL queries in leu of cryptic LDAP ``filters''. LDAP is optimized for
quick lookup of existing data, but DBD::LDAP does support entry inserts,
updates, and deletes with commit/rollback via the standard SQL commands!</P>
<P>LDAP databases are ``heirarchical'' in structure, whereas other DBD-supported
databases are ``relational'' and there is no LDAP-equivalent to SQL ``tables'', so
DBD::LDAP maps a ``table'' interface over the LDAP ``tree'' via a configuration
file you must set up. Each ``table'' is mapped to a common ``base DN''. For
example, consider a typical LDAP database of employees within different
departments within a company. You might have a ``company'' names ``Acme'' and
the root ``dn'' of ``dc=Acme, dc=com'' (Acme.com). Below the company level, are
divisions, ie. ``Widgets'', and ``Blivets''. Each division would have an entry
with a ``dn'' of ``ou=Widgets, dc=Acme, dc=com''. Employees within each division
could have a ``dn'' of ``cn=John Doe, ou=Widgets, dc=Acme, dc=com''.
With DBD::LDAP, we could create tables to access these different levels,
ie. ``top'', which would have a ``DN'' of ``dc=Acme, dc=com'', ``WidgetDivision'' for
``dc=Acme, dc=com''. Tables can also be constained by additional
attribute specifications (filters), ie constraining by ``objectclass'', ie.
``(objectclass=person)''. Then, doing a ``select * from WidgetDivision'' would
display all ``person''s with a ``dn'' containing ``''ou=Widgets, dc=Acme, dc=com``.</P>
<P>
<HR>
<H1><A NAME="installation">INSTALLATION</A></H1>
<PRE>
Installing this module (and the prerequisites from above) is quite
simple. You just fetch the archive, extract it with</PRE>
<PRE>
gzip -cd DBD-LDAP-0.1000.tar.gz | tar xf -</PRE>
<PRE>
(this is for Unix users, Windows users would prefer WinZip or something
similar) and then enter the following:</PRE>
<PRE>
cd DBD-LDAP-#.###
perl Makefile.PL
make
make test</PRE>
<PRE>
If any tests fail, let me know. Otherwise go on with</PRE>
<PRE>
make install</PRE>
<PRE>
Note that you almost definitely need root or administrator permissions.
If you don't have them, read the ExtUtils::MakeMaker man page for
details on installing in your own directories. </PRE>
<P>
<HR>
<H1><A NAME="getting started:">GETTING STARTED:</A></H1>
<PRE>
1) Create a "database", ie. "foo" by creating a text file "foo.ldb". The
general format of this file is:
</PRE>
<PRE>
----------------------------------------------------------
hostname[;port][:[root-dn][:[loginrule]]]
tablename1:[basedn]:[basefilter]:dnattrs:[visableattrs]:[insertattrs]:[ldap_options]
tablename2:[basedn]:[basefilter]:dnattrs:[visableattrs]:[insertattrs]:[ldap_options]
...
----------------------------------------------------------</PRE>
<PRE>
<hostname> represents the ldap server host name.
<port> represents the server's port, default is 389.
<root-dn> if specified, is appended to the end of each tablename's
base-dn.
<loginrule> if specified, converts single word "usernames" to the
appropriate DN, ie:</PRE>
<PRE>
"cn=*,<ROOT>" would convert user name "foo" to "cn=foo, " and
append the "<root-dn>" onto that. The asterisk is converted to
the user-name specified in the "connect" method. If not specified,
the username specified in the "connect" method must be a full DN.
If the "<root-dn>" is not specified, then the "<loginrule>" would
need to be a full DN.</PRE>
<PRE>
tablename - represents the name to be used in SQL statements for a given
set of entries which make up a virtual "table".
basedn - if specified, is appended to the "<root-dn>" to make up the
common base DN for all entries in this table. If "<root-dn>" is
not specified, then a full DN must be specified; otherwise, the
default is the root-dn.
basefilter - if specified, specifies a filter to be used if no "where"-
clause is specified in SQL queries. If a "where"-clause is
specified, the resulting filter is "and"-ed with this one. The
default is "(objectclass=*)".
dnattrs - specifies which attributes that values for which are to be
appended to the left of the basedn to create DNs for new entries
being inserted into the table.
visableattrs - if specified, one or more attributes separated by commas
which will be sought when the SQL statement does not specify
attributes, ie. "select * from tablename". If not specified, the
attributes of the first matching entry are returned and used for
all entries matching a given query.
insertattrs - if specified, one or more attribute/value combinations to be
added to any new entry inserted into the table, usually needed for
objectclass values. The attributes and values usually correspond
to those specivied in the "<basefilter>". The general format is:
attr1=value1[|value2...],attr2=value1...,...
These attributes and values will be joined with any user-specified
values for these attributes.
ldap_options - if specified, can be any one or more of the following:</PRE>
<PRE>
ldap_sizelimit - Limit the number of entries fetch by a query to this
number (0 = no limit) - default: 0.
ldap_timelimit - Limit the search to this number of seconds per query.
(0 = no limit) - default: 0.
ldap_scope - specify the "scope" of the search. Values are: "base",
"one", and "sub", see Net::LDAP docs. Default is "one",
meaning the set of records one level below the basedn. "base"
means search only the basedn, and "sub" means the union
of entries at the "base" level and "one" level below.
ldap_inseparator - specify the separator character/string to be used
in queries to separate multiple values being specified for
a given attribute. Default is "|".
ldap_outseparator - specify the separator character/string to be used
in queryies to separate multiple values displayed as a result
of a query. Default is "|".
ldap_firstonly - only display the 1st value fetched for each attribute
per entry. This makes "ldap_outseparator" unnecessary.</PRE>
<PRE>
2) write your script to use DBI, ie:
</PRE>
<PRE>
#!/usr/bin/perl
use DBI;</PRE>
<PRE>
$dbh = DBI->connect('DBD:LDAP:mydb','me','mypassword') ||
die "Could not connect (".$DBI->err.':'.$DBI->errstr.")!";
...
#CREATE A TABLE, INSERT SOME RECORDS, HAVE SOME FUN!</PRE>
<PRE>
3) get your application working.</PRE>
<P>
<HR>
<H1><A NAME="inserting, fetching and modifying data">INSERTING, FETCHING AND MODIFYING DATA</A></H1>
<PRE>
1st, we'll create a database called "ldapdb" with the tables previously
mentioned in the example in the DESCRIPTION section:
</PRE>
<PRE>
----------------- file "ldapdb.ldb" ----------------
ldapserver:dc=Acme, dc=com:cn=*,<ROOT>
top:::dc
WidgetDivision:ou=Widgets, :&(objectclass=top)(objectclass=person):cn:cn,sn,ou,title,telephonenumber,description,objectclass,dn:objectclass=top|person|organizationalPerson:ldap_outseparator => ":"
----------------------------------------------------</PRE>
<PRE>
The following examples insert some data in a table and fetch it back:
First all data in the string:</PRE>
<PRE>
$dbh->do(<<END_SQL);
INSERT INTO top (ou, cn, objectclass)
VALUES ('Widgets', 'WidgetDivision', 'top|organizationalUnit')
END_SQL</PRE>
<PRE>
Next an example using parameters:</PRE>
<PRE>
$dbh->do("INSERT INTO WidgetDivision (cn,sn,title,telephonenumber) VALUES (?, ?, ?, ?)",
'John Doe','DoeJ','Manager','123-1111');
END_SQL
$dbh->commit();</PRE>
<PRE>
NOTE: Unlike most other DBD modules which support transactions, changes
made do NOT show up until the "commit" function is called, unless
"AutoCommit" is set. This is due to the fact that fetches are done
from the LDAP server and changes do not take effect there until the
Net::LDAP "update" function is called, which is called by "commit".</PRE>
<PRE>
NOTE: The "dn" field is generated automatically from the base "dn" and the
dn component fields specified by "dnattrs", If you try to insert a
value directly into it, it will be ignored. Also, if not specified,
any attribute/value combinations specified in the "insertattrs"
option will be added automatically.</PRE>
<PRE>
To retrieve data, you can use the following:</PRE>
<PRE>
my($query) = "SELECT * FROM WidgetDivision WHERE cn like 'John%' ORDER BY cn";
my($sth) = $dbh->prepare($query);
$sth->execute();
while (my $entry = $sth->fetchrow_hashref) {
print("Found result record: cn = ", $entry->{'cn'},
", phone = ", $row->{'telephonenumber'});
}
$sth->finish();</PRE>
<PRE>
The SQL "SELECT" statement above (combined with the table information
in the "ldapdb.ldb" database file would generate and execute the following
equivalent LDAP Search:</PRE>
<PRE>
base => 'ou=Widgets, dc=Acme, dc=com',
filter => '(&(&(objectclass=top)(objectclass=person))(cn=John*))',
scope => 'one',
attrs => 'cn,sn,ou,title,telephonenumber,description,objectclass,dn'</PRE>
<PRE>
See the DBI(3) manpage for details on these methods. See the</PRE>
<PRE>
Data rows are modified with the UPDATE statement:</PRE>
<PRE>
$dbh->do("UPDATE WidgetDivision SET description = 'Outstanding Employee' WHERE cn = 'John Doe'");</PRE>
<PRE>
NOTE: You can NOT change the "dn" field directly - direct changes will be
ignored. You change the "rdn" component of the "dn" field by changing
the value of the other field(s) which are appended to the base "dn".
Also, if not specified, any attribute/value combinations specified in
the "insertattrs" option will be added automatically.</PRE>
<PRE>
Likewise you use the DELETE statement for removing entries:</PRE>
<PRE>
$dbh->do("DELETE FROM WidgetDivision WHERE description = 'Outstanding Employee'");</PRE>
<P>
<HR>
<H1><A NAME="metadata">METADATA</A></H1>
<PRE>
The following attributes are handled by DBI itself and not by DBD::LDAP,
thus they should all work as expected.</PRE>
<PRE>
PrintError
RaiseError
Warn</PRE>
<PRE>
The following DBI attributes are handled by DBD::LDAP:</PRE>
<PRE>
AutoCommit
Works</PRE>
<PRE>
NUM_OF_FIELDS
Valid after '$sth->execute'</PRE>
<PRE>
NUM_OF_PARAMS
Valid after '$sth->prepare'</PRE>
<PRE>
NAME
Valid after '$sth->execute'; undef for Non-Select statements.</PRE>
<PRE>
NULLABLE
Not really working. Always returns an array ref of one's, as
DBD::LDAP always allows NULL (handled as an empty string).
Valid after `$sth->execute'.</PRE>
<PRE>
LongReadLen
Should work</PRE>
<PRE>
LongTruncOk
Should work</PRE>
<PRE>
These attributes and methods are not supported:</PRE>
<PRE>
bind_param_inout
CursorName</PRE>
<PRE>
In addition to the DBI attributes, you can use the following dbh
attributes. These attributes are read-only after "connect".</PRE>
<PRE>
ldap_dbuser
Current database user.
</PRE>
<PRE>
ldap_HOME
Environment variable specifying a path to search for LDAP
databases (*.sdb) files.</PRE>
<P></P>
<PRE>
=head1 DRIVER PRIVATE METHODS</PRE>
<PRE>
DBI->data_sources()
The `data_sources' method returns a list of "databases" (.ldb files)
found in the current directory and, if specified, the path in
the ldap_HOME environment variable.
</PRE>
<PRE>
$dbh->tables()
This method returns a list of table names specified in the current
database.
Example:</PRE>
<PRE>
my($dbh) = DBI->connect("DBI:LDAP:mydatabase",'me','mypswd');
my(@list) = $dbh->func('tables');</PRE>
<P>
<HR>
<H1><A NAME="other supporting utilities">OTHER SUPPORTING UTILITIES</A></H1>
<P>
<HR>
<H1><A NAME="restrictions">RESTRICTIONS</A></H1>
<PRE>
DBD::LDAP currently treats all data as strings and all fields as
VARCHAR(255).</PRE>
<PRE>
Currently, you must define tables manually in the "<database>.ldb" file
using your favorite text editor. I hope to add support for the SQL
"Create Table", "Alter Table", and "Drop Table" functions to handle this
eventually.</PRE>
<P>
<HR>
<H1><A NAME="todo">TODO</A></H1>
<PRE>
"Create Table", "Alter Table", and "Drop Table" SQL functions for
creating, altering, and deleting the tables defined in the
"<database>.ldb" file.</PRE>
<PRE>
Some kind of datatype support, ie. numeric (for sorting), CHAR for padding,
Long/Blob - for >255 chars per field, etc.</PRE>
<P>
<HR>
<H1><A NAME="known bugs">KNOWN BUGS</A></H1>
<PRE>
none - (yet).
</PRE>
<PRE>
=head1 SEE ALSO</PRE>
<PRE>
Net::LDAP(3), DBI(3), perl(1)</PRE>
<IMG SRC="http://turnerville.wwol.com/cgi-bin/access_log.pl?DBDLdap">
</BODY>
</HTML>
|
