summaryrefslogtreecommitdiffstats
path: root/servers/slapd/back-sql/docs
diff options
context:
space:
mode:
Diffstat (limited to 'servers/slapd/back-sql/docs')
-rw-r--r--servers/slapd/back-sql/docs/bugs16
-rw-r--r--servers/slapd/back-sql/docs/concept1
-rw-r--r--servers/slapd/back-sql/docs/install86
-rw-r--r--servers/slapd/back-sql/docs/platforms8
-rw-r--r--servers/slapd/back-sql/docs/todo12
5 files changed, 123 insertions, 0 deletions
diff --git a/servers/slapd/back-sql/docs/bugs b/servers/slapd/back-sql/docs/bugs
new file mode 100644
index 0000000..ae47e67
--- /dev/null
+++ b/servers/slapd/back-sql/docs/bugs
@@ -0,0 +1,16 @@
+1) driver name comparison for MS SQL Server workaround is realy kinda dirty
+ hack, but for now i don't know how to code it more carefully
+2) another dirty hack: length of LONGVARCHAR and LONGVARBINARY fields is
+ currently set to MAX_ATTR_LEN. Maybe such fields must be handled with
+ SQLGetData() instead of SQLBindCol(), but it is said in documentation,
+ that it is guaranteed to work only when such column goes after last bound
+ column. Or should we get ALL columns with SQLGetData (then something like
+ _SQLFetchAsStrings() wrapper would do SQLGetData() for all columns)...
+3) in some cases (particularly, when using OpenLink Generic ODBC driver with
+ MS SQL Server), it returns "Function sequence error" after all records are
+ fetched. I really don't know what it means, and after all
+ - it works with any other driver I tried
+4) ldapsearch sometimes refuses to show some attributes ("NOT PRINTABLE" diags)
+ on Win32 (on linux everything's fine)
+5) back-sql crashes on invalid filters (to be fixed ASAP)
+ \ No newline at end of file
diff --git a/servers/slapd/back-sql/docs/concept b/servers/slapd/back-sql/docs/concept
new file mode 100644
index 0000000..ed29047
--- /dev/null
+++ b/servers/slapd/back-sql/docs/concept
@@ -0,0 +1 @@
+The SQL backend is described in the slapd-sql(5) manual page.
diff --git a/servers/slapd/back-sql/docs/install b/servers/slapd/back-sql/docs/install
new file mode 100644
index 0000000..230bf0a
--- /dev/null
+++ b/servers/slapd/back-sql/docs/install
@@ -0,0 +1,86 @@
+PLEASE READ THIS WHOLE FILE AND CONCEPT, BECAUSE THEY COVER SEVERAL STICKY
+ISSUES THAT YOU WILL PROBABLY STUMBLE ACROSS ANYWAY
+
+1. Build
+To build slapd with back-sql under Unix you need to build and install
+iODBC 2.50.3 (later versions should probably work, but not earlier),
+or unixODBC (you will have to change -liodbc to -lodbc then).
+Then, at top of OpenLDAP source tree, run
+"configure <other options you need> --enable-sql", then "make" -
+this should build back-sql-enabled slapd, provided that you have iODBC/unixODBC
+libraries and include files in include/library paths, "make install"...
+In other words, follow installation procedure described in OpenLDAP
+Administrators Guide, adding --enable-sql option to configure, and
+having iODBC/unixODBC libraries installed an accessible by compiler.
+
+Under Win32/MSVC++, I modified the workspace so that back-sql is built into
+slapd automatically, since MS ODBC manager, odbc32.dll, is included in
+standard library pack, and it does no bad even if you don't plan to use it.
+I also could provide precompiled executables for those who don't have MSVC.
+Note that Win32 port of OpenLDAP itself is experimental, and thus doesn't
+provide very convenient build environment (yet).
+
+2. Tune datasources and slapd.conf
+Next, you need to define ODBC datasource with data you want to publish
+with help of back-sql. Assuming that you have your data in some SQL-compliant
+RDBMS, and have installed proper ODBC driver for this RDBMS, this is as simple
+as adding a record into odbc.ini (for iODBC/unixODBC), or using ODBC wizard in
+Control Panel (for odbc32).
+Next, you need to add appropriate "database" record to your slapd.conf.
+See samples provided in "back-sql/RDBMS_DEPENDENT/" subdirectory.
+
+Several things worth noting about ODBC:
+- "dbname" directive stands for ODBC datasource name (DSN),
+ not the name of your database in RDBMS context
+- ODBC under Unix is not so common as under Windows, so you could have
+ problems with Unix drivers for your RDBMS. Visit http://www.openlinksw.com,
+ they provide a multitier solution which allows connecting to DBMSes on
+ different platforms, proxying and other connectivity and integration issues.
+ They also support iODBC, and have good free customer service through
+ newsserver (at news.openlinksw.com).
+ Also worth noting are: ODBC-ODBC bridge by EasySoft (which was claimed
+ by several people to be far more effective and stable than OpenLink),
+ OpenRDA package etc.
+- be careful defining RDBMS connection parameters, you'll probably need only
+ "dbname" directive - all the rest can be defined in datasource. Every other
+ directive is used to override value stored in datasource definition.
+ Maybe you will want to use dbuser/dbpasswd to override credentials defined in datasource
+- full list of configuration directives supported is available in file "guide",
+ you may also analyze output of 'slapd -d 5' to find out some useful
+ directives for redefining default queries
+
+3. Creating and using back-sql metatables
+Read the file "concept" to understand, what metainformation you need to add,
+and what for... ;)
+See SQL scripts and slapd.conf files in samples directory.
+Find subdirectory in "rdbms_depend/" corresponding to your RDBMS (Oracle,
+MS SQL Server and mySQL are listed there currently), or copy and edit
+any of these to conform to SQL dialect of your RDBMS (please be sure to send
+me scripts and notes for new RDBMSes ;).
+
+Execute "backsql_create.sql" from that subdirectory (or edited one),
+so that the tables it creates appear in the same
+context with the data you want to export through LDAP (under same DB/user,
+or whatever is needed in RDBMS you use). You can use something like
+"mysql < xxx.sql" for mySQL, Query Analyzer+Open query file for MS SQL,
+sqlplus and "@xxx.sql" for Oracle.
+
+You may well want to try it with test data first, and see how metatables
+are used. Create test data and metadata by running testdb_create.sql,
+testdb_data.sql, and testdb_metadata.sql scripts (again, adopted for your
+RDBMS, and in the same context as metatables you created before), and
+tune slapd.conf to use your test DB.
+
+4. Testing
+To diagnose back-sql, run slapd with debug level TRACE ("slapd -d 5" will go).
+Then, use some LDAP client to query corresponding subtree (for test database,
+you could for instance search one level from "o=sql,c=RU"). I personally used
+saucer, which is included in OpenLDAP package (it builds automatically under
+Unix/GNU configure and for MSVC I added appropriate project to workspace).
+And also Java LDAP browser-editor (see link somewhere on OpenLDAP site) to
+test ADD/DELETE/MODIFY operations on Oracle and MS SQL.
+
+See file "platforms" if you encounter connection problems - you may find
+a hint for your RDBMS or OS there. If you are stuck - please contact me at
+mit@openldap.org, or (better) post an issue through OpenLDAP's Issue Tracking
+System (see http:/www.openldap.org/its).
diff --git a/servers/slapd/back-sql/docs/platforms b/servers/slapd/back-sql/docs/platforms
new file mode 100644
index 0000000..65e326a
--- /dev/null
+++ b/servers/slapd/back-sql/docs/platforms
@@ -0,0 +1,8 @@
+Platforms and configurations it has been tested on:
+
+General:
+ - ODBC managers: iODBC,unixODBC under unixes, odbc32.dll under Win32 family
+ - OSes: Linux/glibc, FreeBSD, OpenBSD, Solaris 2.6, Win98, WinNT, Win2000 server
+ - RDBMSes: Oracle 7/8/8i, MS SQL Server 6.5/7, mySQL
+ - access suites: OpenLink DAS, EasySoft OOB, various win32 drivers
+
diff --git a/servers/slapd/back-sql/docs/todo b/servers/slapd/back-sql/docs/todo
new file mode 100644
index 0000000..9d8736f
--- /dev/null
+++ b/servers/slapd/back-sql/docs/todo
@@ -0,0 +1,12 @@
+1) must add alias handling
+2) [sizelimit moved to frontend]
+ must set time limit when preparing all queries, and check size limit
+3) there was expressed a need to have access to IP in while constructing
+ queries, to have response alter in accordance to client IP. Will add
+ preprocessor for values in metatables, which would substitute things
+ like "$IP$".
+4) must handle NOT filters (see ITS#2652)
+5) must map attribute types and syntaxes between LDAP and SQL types (e.g.
+ use BLOBs for octet streams)
+6) must define another mech to add auxiliary objectClass to all entries
+ according to ldap_at_mappings (ldap_entry_objclasses has limitations)