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