2 <title>web_ldap_usage</title>
6 <h2>web_ldap version 1.1, OpenLDAP variant</h2>
8 This is an OpenLDAP port of the web_ldap program.
11 The files provided in the file set for 'web_ldap'
12 were developed under the GNU General Public License (GPL).
13 Under the GPL, the source code is freely-distributed and available
14 to the general public. There is no warranty on the software,
15 and it does not come with support, however, I would appreciate
16 it if you emailed any bug-fixes you create to me
17 (<a href="mailto:jens@colomar.com">jens@colomar.com</a>) and
18 <a href="mailto:OpenLDAP-its@OpenLDAP.org">OpenLDAP-its@OpenLDAP.org</a>.
20 All code here is generic ISO C, allowing most Unix compilers
21 to generate the required object files and executable images.
22 It was tested against an Apache HTTPD server and uses no
23 special HTML functionality that does not appear within V 3.x
24 versions of Netscapes or Microsofts Web Browsers. The goal was
25 to create a starting point example to help people build
26 effective interactive HTML based LDAP clients.
28 <h3>Introduction:</h3>
30 The 'web_ldap' package is a complete LDAP application that
31 provides a functional Web Server Based client. The intent
32 is to give you a working example that you can expand upon
33 for your own needs. It does not solve a specific problem
34 for you, rather it solves a general problem by giving
35 you a functional starting point from where to begin your
36 development efforts. It runs under Unix.
38 The application consists of a number of C programs, header
39 files, an HTML file with form entry, a configuration file
40 and a sample makefile. You will need the LDAP SDK for your
41 specific Unix System (both the UofM libraries and Netscape
42 libraries - which are also free - have been tested).
44 The tool allows you to specify that actions taken
45 be logged to a file. This provides you a method by which
46 you can build out larger applications and see what is happening.
48 The application can be run interactively (without use of
49 a Web Browser) but was intended for use as an HTML LDAP Web
52 One thing to consider when running a program of this nature
53 is that there are 2 totally different sets of environments
54 involved. The program is written assuming very little in
55 the way of file/directory organization. As such it looks for
56 files either in the directory it was run from, or where ever
57 you have configured your Web Server to look for things.
59 The C CGI program will attempt to open a default configuration
60 file called 'web_ldap.cfg'. If you set the debug mode on
61 in the configuration file, it will also attempt to create
62 a log file called 'web_ldap.log' in the same directory as
63 the 'web_ldap.cfg' files appears in.
65 The 2 environments are 'Interactive' and 'Web Server'.
67 When you execute the application from a command line such as:
69 > web_ldap DEF cn=jens moller
71 All actions take place in the same directory that the web_ldap
72 program resides in. Most people would typically build an
73 application of this nature in one of their own directories and
74 this would give them Read/Write access to all of the files
75 associated with the program. Any file restrictions or capabilities
76 that you have will be enabled as part of your session.
78 This is quite different than when you ask a Web Server to
79 execute the program for you. The Web Server is typically
80 using the user 'nobody'. This is not you, its a separate
81 application user and it may not have access to the same
82 files that you have nor the same process capabilities.
84 When your program executes from a Web Browser, you will
87 http://my.system.com/cgi-bin/web_ldap
90 displayed by the Web Browser as the URL that its executing.
91 The Web Server is executing the program on your behalf.
92 File protections normally cause initial problems, possibly
93 because the Web Browser doesn't own the files or doesn't
94 have execute access. For your initial testing, please set these
95 files to full access - ie. 'chmod 777 web_ldap*' - You can
96 adjust the file protections once you get everything working.
97 If you get errors - start with this simple change.
99 <h3>Building the application:</h3>
101 Requires ISO C (your standard OS compiler or GCC should
104 Under OpenLDAP, you should build with the following commands after
105 having configured and built OpenLDAP itself:
112 <h3>Configuration:</h3>
114 Its a very simple tool that allows you to make LDAP requests
115 to any existing LDAP Directory Server. By default, it
116 attempts to connect to 'ldap.bigfoot.com', which is a
117 commercial LDAP server on the Internet - usually available
120 To specify a different LDAP server, you could either modify
121 the program to default elsewhere, or you could modify the
122 existing 'web_ldap.cfg' file, or create another one with
125 NOTE: A '#' in the first column of any line
126 in the configuration file is considered a comment.
129 The configuration file allows you specify:
133 This is the servername. For example:
135 server:ldap.bigfoot.com,389
137 connects you up to port 389 on the ldap server 'ldap.bigfoot.com'.
138 You can specify one of your own servers here if you desire.
144 This is where within a tree you want to start looking. For
145 'ldap.bigfoot.com', you would leave this blank and it will
146 look in all the trees. For many companies a specific tree
147 structure will be defined, and you will want to specify the
148 highest point in the tree structure that defines the area that
149 you are interested in. For example, if you have a tree that
150 starts at 'c=US', and branches at 'o=ABC, c=US' and
151 'o=XYZ, c=US', you could specify:
155 and search both 'o=ABC, c=US' and 'o=XYZ, c=US', or
156 if you only wanted to search against 'o=ABC, c=US',
159 searchbase:o=ABC, c=US
161 If you want to turn on a simple Debug mode, you can specify any number
162 other than zero for 'debug:'. For example:
166 turns on the Debug logging mode, and
170 turns it off. Debug logging simply creates a file called
171 'web_ldap.log' in the same directory that the web_ldap
172 executable is located. It flushes everything after each
173 event, so if it gets stuck anywhere, you will be able
174 to see it. It also time-stamps most of the results, so you
175 can get an idea where things are running faster and/or
176 slower for different queries.
178 The remainder of the configuration file is where you list
179 the attributes that you are interested in displaying.
181 You could list parameters (up to 100) like:
187 and that is all it will return. If you don't specify
188 anything, it returns everything it finds. if you
189 specify an attribute that the directory has never
190 heard of (ie. its not a member of any object class
191 anyone has defined), that attribute will simply be
192 ignored. If you misspell an attribute name and wonder
193 why it never gets listed in the results - this might be
194 why. If you specify an attribute that some users have and
195 others don't, only ones with that attribute will list
198 Directory data can be multi-valued. This means that any
199 attribute could have multiple values. This application will
200 list all the values it finds for any given attribute.
203 <h3>Where to put the files:</h3>
205 If running this interactively (from a Unix shell prompt),
206 all the files can reside in any of your home directories.
207 I suggest that you test the application in your home
210 If running this application from a Web Server, you need
211 to find out where the Web Server keeps its cgi applications
212 and where it keeps its html applications. This varies
213 from operating system to operating system and Web Server
216 Once you have located the cgi-bin (or equivalent) directory,
217 put these 2 files there:
222 then make sure that these files are accessible to the Web
223 Server by executing the Unix shell command:
225 > chmod 777 web_ldap*
227 Now find the HTML source directory. Copy
231 to this directory. Make sure that this file is accessible to the Web
232 Server by executing the Unix shell command:
234 > chmod 777 web_ldap*
237 <h3>Running the application:</h3>
239 Test it in your own directory by entering:
243 This should connect to 'ldap.bigfoot.com' and try to find a number
244 of entries (it does when I try it). You will notice that it
245 outputs results in the form of an HTML file - this is what it
246 is supposed to do. If you leave out the 'DEF', you will get the
249 <p>++ Error - This script should be referenced with a METHOD of POST.
251 as a part of your result with no LDAP data returned.
253 Interactively, the program assumes that you will always pass it at least
254 the name of the Configuration file ('DEF' tells it to use the default
255 configuration file). If there is no configuration file, it still will
256 find 'ldap.bigfoot.com'.
258 Once you have it working there, try the version in the HTML directory.
259 To do so, enter your WEB Servers URL, the cgi-bin directory reference
260 and then the application name, all separated by slashes. For example,
261 if your Web Server URL is 'http://my.server.com', then you will want
264 http://my.server.com/cgi-bin/web_ldap
266 NOTE: You can only run cgi scripts out of a directory that the Web Server
267 allows. It is unlikely that you can execute Web Server CGI applications
268 from your own directory.
270 This will provide a simple Web Based form. It will have 2 user entry
271 fields. The first allows you to enter an LDAP request. The second
272 allows you to specify a configuration file (it defaults to 'DEF').
274 Enter a simple LDAP request, such as the ones shown and see if you
275 get back a response. You should if connected to 'ldap.bigfoot.com'.
278 <h3>Now that you have it working:</h3>
280 Feel free to adapt this program to fit your needs. You will need
281 to have the 'dn' in order to do updates. It is recovered within
282 the program, so you can save it for use once you retrieve it
283 (it is listed in the web_ldap.log file of you enable debug mode).
285 This program does not update anything. The goal was to create a very
286 simple and expandable LDAP client and provide the complete source
287 code for doing it. To this goal, it is successful. From here
288 you should be able to experiment with the interfaces and create
289 new functionality to suit your given needs.
291 This was tested against the UofM V 3.3 LDAP Libraries and the Netscape
292 V 1.x and V 3.x SDK under both Irix 6.2 (Silicon Graphics) and
293 Solaris 2.6 (Sun). I don't have other hardware or OS's to test
297 <h3>Usage Information:</h3>
299 If you want to find out what attributes are being used, you can enable
300 the application to tell you all that it finds. Do this by simply
301 not defining any attributes within the configuration file. It will
302 list all the attributes it finds. You could create a special configuration
303 file specifically for this purpose.
305 If you are getting fatal errors from your Web Server when you attempt to
306 execute a command, please try the same command using interactive mode. Look
307 to see if the HTML being generated makes sense or not. If the HTML
308 looks good, run it again interactively and pipe the results to a file, then
309 attempt to submit the resulting file as the URL. If it works, it is
310 likely that the environment you run is different than the one the Web
311 server is using - Unix file protections frequently are a cause of these
312 problems. If you can't determine what is different, discuss the problem
313 with your Unix system administrator - is is likely a resource problem.
314 If you add code that causes problems, but you still get a result, try the
315 application in interactive mode and verify the HTML being generated. Any
316 additional HTML code you add may need to to have proper termination syntax
317 (tables are very touchy about this), and you may need to further enhance
318 your changes to compensate.
320 When creating new applications, please test your
321 results on both Netscape's Web Browser and Internet
322 Explorer. Nothing is more irritating to end users than getting different
323 results based on their Web Browser selection.
325 The Unix Command line will not allow you to pass some characters into
326 an application unless you surround the characters or command with quotes.
327 Some common examples of executing web_ldap interactively are:
329 > web_ldap DEF "cn=j*moller"
331 > web_ldap DEF cn=jens moller
333 The command with the '*' in it requires quotes around it. Also note
334 that the application only allows the LDAP command to use up to 3 argv
335 values. This is as a limitation of the current parsing within the program
336 of argc/argv parameters. You could alter the program, or simply put
337 quotes around the LDAP request. Enable the debug mode within the
338 configuration file if you feel that the application is losing
339 arguments to see what its operating against. When operated by the Web Server,
340 and passing in FORM data - you won't have this limitation, and you don't
343 You can pass hidden fields from the Web Form into the web_ldap program.
344 An example is shown with the name of 'FORM' having a value of '300'.
345 You can create additional hidden fields, named anything you want them
346 to be, with any value you want. These can be used to define existing
347 options (such as which configuration file to use), or other options
348 that your modified web_ldap.c program may want to have passed to it.
351 Jens Moller - Jens@colomar.com -
352 <a href="http://www.colomar.com">COLOMAR Group</a>.<br>
354 <a href="http://www.OpenLDAP.org/">OpenLDAP</a> - OpenLDAP-devel@OpenLDAP.org.