openldap/contrib/web_ldap/web_ldap_usage.txt

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.