git.sur5r.net Git - openldap/blob - servers/slapd/back-sql/docs/install

   1 PLEASE READ THIS WHOLE FILE AND CONCEPT, BECAUSE THEY COVER SEVERAL STICKY
   2 ISSUES THAT YOU WILL PROBABLY STUMBLE ACROSS ANYWAY
   3
   4 1. Build
   5 To build slapd with back-sql under Unix you need to build and install
   6 iODBC 2.50.3 (later versions should probably work, but not earlier),
   7 or unixODBC (you will have to change -liodbc to -lodbc then).
   8 Then, at top of OpenLDAP source tree, run
   9 "configure <other options you need> --enable-sql", then "make" -
  10 this should build back-sql-enabled slapd, provided that you have iODBC/unixODBC
  11 libraries and include files in include/library paths, "make install"...
  12 In other words, follow installation procedure described in OpenLDAP
  13 Administrators Guide, adding --enable-sql option to configure, and
  14 having iODBC/unixODBC libraries installed an accessible by compiler.
  15
  16 Under Win32/MSVC++, I modified the workspace so that back-sql is built into
  17 slapd automatically, since MS ODBC manager, odbc32.dll, is included in
  18 standard library pack, and it does no bad even if you don't plan to use it.
  19 I also could provide precompiled executables for those who don't have MSVC.
  20 Note that Win32 port of OpenLDAP itself is experimental, and thus doesn't
  21 provide very convenient build environment (yet).
  22
  23 2. Tune datasources and slapd.conf
  24 Next, you need to define ODBC datasource with data you want to publish
  25 with help of back-sql. Assuming that you have your data in some SQL-compliant
  26 RDBMS, and have installed proper ODBC driver for this RDBMS, this is as simple
  27 as adding a record into odbc.ini (for iODBC/unixODBC), or using ODBC wizard in
  28 Control Panel (for odbc32).
  29 Next, you need to add appropriate "database" record to your slapd.conf.
  30 See samples provided in "back-sql/RDBMS_DEPENDENT/" subdirectory.
  31
  32 Several things worth noting about ODBC:
  33 - "dbname" directive stands for ODBC datasource name (DSN),
  34   not the name of your database in RDBMS context
  35 - ODBC under Unix is not so common as under Windows, so you could have
  36   problems with Unix drivers for your RDBMS. Visit http://www.openlinksw.com,
  37   they provide a multitier solution which allows connecting to DBMSes on
  38   different platforms, proxying and other connectivity and integration issues.
  39   They also support iODBC, and have good free customer service through
  40   newsserver (at news.openlinksw.com).
  41   Also worth noting are: ODBC-ODBC bridge by EasySoft (which was claimed
  42    by several people to be far more effective and stable than OpenLink),
  43    OpenRDA package etc.
  44 - be careful defining RDBMS connection parameters, you'll probably need only
  45   "dbname" directive - all the rest can be defined in datasource. Every other
  46   directive is used to override value stored in datasource definition.
  47   Maybe you will want to use dbuser/dbpasswd to override credentials defined in datasource
  48 - full list of configuration directives supported is available in file "guide",
  49   you may also analyze output of 'slapd -d 5' to find out some useful
  50   directives for redefining default queries
  51
  52 3. Creating and using back-sql metatables
  53 Read the file "concept" to understand, what metainformation you need to add,
  54 and what for... ;)
  55 See SQL scripts and slapd.conf files in samples directory.
  56 Find subdirectory in "rdbms_depend/" corresponding to your RDBMS (Oracle,
  57 MS SQL Server and mySQL are listed there currently), or copy and edit
  58 any of these to conform to SQL dialect of your RDBMS (please be sure to send
  59 me scripts and notes for new RDBMSes ;).
  60
  61 Execute "backsql_create.sql" from that subdirectory (or edited one),
  62 so that the tables it creates appear in the same
  63 context with the data you want to export through LDAP (under same DB/user,
  64 or whatever is needed in RDBMS you use). You can use something like
  65 "mysql < xxx.sql" for mySQL, Query Analyzer+Open query file for MS SQL,
  66 sqlplus and "@xxx.sql" for Oracle.
  67
  68 You may well want to try it with test data first, and see how metatables
  69 are used. Create test data and metadata by running testdb_create.sql,
  70 testdb_data.sql, and testdb_metadata.sql scripts (again, adopted for your
  71 RDBMS, and in the same context as metatables you created before), and
  72 tune slapd.conf to use your test DB.
  73
  74 4. Testing
  75 To diagnose back-sql, run slapd with debug level TRACE ("slapd -d 5" will go).
  76 Then, use some LDAP client to query corresponding subtree (for test database,
  77 you could for instance search one level from "o=sql,c=RU"). I personally used
  78 saucer, which is included in OpenLDAP package (it builds automatically under
  79 Unix/GNU configure and for MSVC I added appropriate project to workspace).
  80 And also Java LDAP browser-editor (see link somewhere on OpenLDAP site) to
  81 test ADD/DELETE/MODIFY operations on Oracle and MS SQL.
  82
  83 See file "platforms" if you encounter connection problems - you may find
  84 a hint for your RDBMS or OS there. If you are stuck - please contact me at
  85 mit@openldap.org, or (better) post an issue through OpenLDAP's Issue Tracking
  86 System (see http:/www.openldap.org/its).