## web_ldap version 1.1, OpenLDAP variant

This is an OpenLDAP port of the web_ldap program.

The files provided in the file set for 'web_ldap' were developed under the GNU General Public License (GPL). Under the GPL, the source code is freely-distributed and available to the general public. There is no warranty on the software, and it does not come with support, however, I would appreciate it if you emailed any bug-fixes you create to me (jens@colomar.com) and OpenLDAP-its@OpenLDAP.org.

All code here is generic ISO C, allowing most Unix compilers to generate the required object files and executable images. It was tested against an Apache HTTPD server and uses no special HTML functionality that does not appear within V 3.x versions of Netscapes or Microsofts Web Browsers. The goal was to create a starting point example to help people build effective interactive HTML based LDAP clients.

### Introduction:

The 'web_ldap' package is a complete LDAP application that provides a functional Web Server Based client. The intent is to give you a working example that you can expand upon for your own needs. It does not solve a specific problem for you, rather it solves a general problem by giving you a functional starting point from where to begin your development efforts. It runs under Unix.

The application consists of a number of C programs, header files, an HTML file with form entry, a configuration file and a sample makefile. You will need the LDAP SDK for your specific Unix System (both the UofM libraries and Netscape libraries - which are also free - have been tested).

The tool allows you to specify that actions taken be logged to a file. This provides you a method by which you can build out larger applications and see what is happening.

The application can be run interactively (without use of a Web Browser) but was intended for use as an HTML LDAP Web page application.

One thing to consider when running a program of this nature is that there are 2 totally different sets of environments involved. The program is written assuming very little in the way of file/directory organization. As such it looks for files either in the directory it was run from, or where ever you have configured your Web Server to look for things.

The C CGI program will attempt to open a default configuration file called 'web_ldap.cfg'. If you set the debug mode on in the configuration file, it will also attempt to create a log file called 'web_ldap.log' in the same directory as the 'web_ldap.cfg' files appears in.

The 2 environments are 'Interactive' and 'Web Server'.

When you execute the application from a command line such as:

         > web_ldap DEF cn=jens moller

All actions take place in the same directory that the web_ldap program resides in. Most people would typically build an application of this nature in one of their own directories and this would give them Read/Write access to all of the files associated with the program. Any file restrictions or capabilities that you have will be enabled as part of your session.

This is quite different than when you ask a Web Server to execute the program for you. The Web Server is typically using the user 'nobody'. This is not you, its a separate application user and it may not have access to the same files that you have nor the same process capabilities.

When your program executes from a Web Browser, you will see something like:

        http://my.system.com/cgi-bin/web_ldap

displayed by the Web Browser as the URL that its executing. The Web Server is executing the program on your behalf. File protections normally cause initial problems, possibly because the Web Browser doesn't own the files or doesn't have execute access. For your initial testing, please set these files to full access - ie. 'chmod 777 web_ldap*' - You can adjust the file protections once you get everything working. If you get errors - start with this simple change.

### Building the application:

Requires ISO C (your standard OS compiler or GCC should work fine).

Under OpenLDAP, you should build with the following commands after having configured and built OpenLDAP itself:

    	cd contrib/web_ldap
    	make depend
    	make

### Configuration:

Its a very simple tool that allows you to make LDAP requests to any existing LDAP Directory Server. By default, it attempts to connect to 'ldap.bigfoot.com', which is a commercial LDAP server on the Internet - usually available from anywhere.

To specify a different LDAP server, you could either modify the program to default elsewhere, or you could modify the existing 'web_ldap.cfg' file, or create another one with a different name.

NOTE: A '#' in the first column of any line in the configuration file is considered a comment.

The configuration file allows you specify:

      server:

This is the servername. For example:

      server:ldap.bigfoot.com,389

connects you up to port 389 on the ldap server 'ldap.bigfoot.com'. You can specify one of your own servers here if you desire.

Next you will see:

      searchbase:

This is where within a tree you want to start looking. For 'ldap.bigfoot.com', you would leave this blank and it will look in all the trees. For many companies a specific tree structure will be defined, and you will want to specify the highest point in the tree structure that defines the area that you are interested in. For example, if you have a tree that starts at 'c=US', and branches at 'o=ABC, c=US' and 'o=XYZ, c=US', you could specify:

      searchbase:c=US

and search both 'o=ABC, c=US' and 'o=XYZ, c=US', or if you only wanted to search against 'o=ABC, c=US', you could specify:

      searchbase:o=ABC, c=US

If you want to turn on a simple Debug mode, you can specify any number other than zero for 'debug:'. For example:

      debug:1

turns on the Debug logging mode, and

      debug:0

turns it off. Debug logging simply creates a file called 'web_ldap.log' in the same directory that the web_ldap executable is located. It flushes everything after each event, so if it gets stuck anywhere, you will be able to see it. It also time-stamps most of the results, so you can get an idea where things are running faster and/or slower for different queries.

The remainder of the configuration file is where you list the attributes that you are interested in displaying.

You could list parameters (up to 100) like:

      cn
      givenname
      sn

and that is all it will return. If you don't specify anything, it returns everything it finds. if you specify an attribute that the directory has never heard of (ie. its not a member of any object class anyone has defined), that attribute will simply be ignored. If you misspell an attribute name and wonder why it never gets listed in the results - this might be why. If you specify an attribute that some users have and others don't, only ones with that attribute will list a value for it.

Directory data can be multi-valued. This means that any attribute could have multiple values. This application will list all the values it finds for any given attribute.

### Where to put the files:

If running this interactively (from a Unix shell prompt), all the files can reside in any of your home directories. I suggest that you test the application in your home directory first.

If running this application from a Web Server, you need to find out where the Web Server keeps its cgi applications and where it keeps its html applications. This varies from operating system to operating system and Web Server to Web Server.

Once you have located the cgi-bin (or equivalent) directory, put these 2 files there:

      web_ldap
      web_ldap.cfg

then make sure that these files are accessible to the Web Server by executing the Unix shell command:

      > chmod 777 web_ldap*

Now find the HTML source directory. Copy

      web_ldap.html

to this directory. Make sure that this file is accessible to the Web Server by executing the Unix shell command:

      > chmod 777 web_ldap*

### Running the application:

Test it in your own directory by entering:

      > web_ldap DEF

This should connect to 'ldap.bigfoot.com' and try to find a number of entries (it does when I try it). You will notice that it outputs results in the form of an HTML file - this is what it is supposed to do. If you leave out the 'DEF', you will get the error:

    <p>++ Error - This script should be referenced with a METHOD of POST.

as a part of your result with no LDAP data returned.

Interactively, the program assumes that you will always pass it at least the name of the Configuration file ('DEF' tells it to use the default configuration file). If there is no configuration file, it still will find 'ldap.bigfoot.com'.

Once you have it working there, try the version in the HTML directory. To do so, enter your WEB Servers URL, the cgi-bin directory reference and then the application name, all separated by slashes. For example, if your Web Server URL is 'http://my.server.com', then you will want to specify the URL:

      http://my.server.com/cgi-bin/web_ldap

NOTE: You can only run cgi scripts out of a directory that the Web Server allows. It is unlikely that you can execute Web Server CGI applications from your own directory.

This will provide a simple Web Based form. It will have 2 user entry fields. The first allows you to enter an LDAP request. The second allows you to specify a configuration file (it defaults to 'DEF').

Enter a simple LDAP request, such as the ones shown and see if you get back a response. You should if connected to 'ldap.bigfoot.com'.

### Now that you have it working:

Feel free to adapt this program to fit your needs. You will need to have the 'dn' in order to do updates. It is recovered within the program, so you can save it for use once you retrieve it (it is listed in the web_ldap.log file of you enable debug mode).

This program does not update anything. The goal was to create a very simple and expandable LDAP client and provide the complete source code for doing it. To this goal, it is successful. From here you should be able to experiment with the interfaces and create new functionality to suit your given needs.

This was tested against the UofM V 3.3 LDAP Libraries and the Netscape V 1.x and V 3.x SDK under both Irix 6.2 (Silicon Graphics) and Solaris 2.6 (Sun). I don't have other hardware or OS's to test against here.

### Usage Information:

If you want to find out what attributes are being used, you can enable the application to tell you all that it finds. Do this by simply not defining any attributes within the configuration file. It will list all the attributes it finds. You could create a special configuration file specifically for this purpose.

If you are getting fatal errors from your Web Server when you attempt to execute a command, please try the same command using interactive mode. Look to see if the HTML being generated makes sense or not. If the HTML looks good, run it again interactively and pipe the results to a file, then attempt to submit the resulting file as the URL. If it works, it is likely that the environment you run is different than the one the Web server is using - Unix file protections frequently are a cause of these problems. If you can't determine what is different, discuss the problem with your Unix system administrator - is is likely a resource problem. If you add code that causes problems, but you still get a result, try the application in interactive mode and verify the HTML being generated. Any additional HTML code you add may need to to have proper termination syntax (tables are very touchy about this), and you may need to further enhance your changes to compensate.

When creating new applications, please test your results on both Netscape's Web Browser and Internet Explorer. Nothing is more irritating to end users than getting different results based on their Web Browser selection.

The Unix Command line will not allow you to pass some characters into an application unless you surround the characters or command with quotes. Some common examples of executing web_ldap interactively are:

      > web_ldap DEF "cn=j*moller"

      > web_ldap DEF cn=jens moller

The command with the '*' in it requires quotes around it. Also note that the application only allows the LDAP command to use up to 3 argv values. This is as a limitation of the current parsing within the program of argc/argv parameters. You could alter the program, or simply put quotes around the LDAP request. Enable the debug mode within the configuration file if you feel that the application is losing arguments to see what its operating against. When operated by the Web Server, and passing in FORM data - you won't have this limitation, and you don't need quotes.

You can pass hidden fields from the Web Form into the web_ldap program. An example is shown with the name of 'FORM' having a value of '300'. You can create additional hidden fields, named anything you want them to be, with any value you want. These can be used to define existing options (such as which configuration file to use), or other options that your modified web_ldap.c program may want to have passed to it.

Jens Moller - Jens@colomar.com - COLOMAR Group.
OpenLDAP - OpenLDAP-devel@OpenLDAP.org.