mirror of
https://git.openldap.org/openldap/openldap.git
synced 2024-12-21 03:10:25 +08:00
355 lines
14 KiB
HTML
355 lines
14 KiB
HTML
<html>
|
|
<title>web_ldap_usage</title>
|
|
<body text="#000000"
|
|
bgcolor="#FFFFFF">
|
|
|
|
<h2>web_ldap version 1.1, OpenLDAP variant</h2>
|
|
|
|
This is an OpenLDAP port of the web_ldap program.
|
|
<p>
|
|
<i>
|
|
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
|
|
(<a href="mailto:jens@colomar.com">jens@colomar.com</a>) and
|
|
<a href="mailto:OpenLDAP-bugs@OpenLDAP.org">OpenLDAP-bugs@OpenLDAP.org</a>.
|
|
<p>
|
|
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.
|
|
</i>
|
|
<h3>Introduction:</h3>
|
|
|
|
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.
|
|
<p>
|
|
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).
|
|
<p>
|
|
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.
|
|
<p>
|
|
The application can be run interactively (without use of
|
|
a Web Browser) but was intended for use as an HTML LDAP Web
|
|
page application.
|
|
<p>
|
|
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.
|
|
<p>
|
|
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.
|
|
<p>
|
|
The 2 environments are 'Interactive' and 'Web Server'.
|
|
<p>
|
|
When you execute the application from a command line such as:
|
|
<pre>
|
|
> web_ldap DEF cn=jens moller
|
|
</pre>
|
|
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.
|
|
<p>
|
|
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.
|
|
<p>
|
|
When your program executes from a Web Browser, you will
|
|
see something like:
|
|
<pre>
|
|
http://my.system.com/cgi-bin/web_ldap
|
|
|
|
</pre>
|
|
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.
|
|
|
|
<h3>Building the application:</h3>
|
|
|
|
Requires ISO C (your standard OS compiler or GCC should
|
|
work fine).
|
|
<p>
|
|
Under OpenLDAP, you should build with the following commands after
|
|
having configured and built OpenLDAP itself:
|
|
<pre>
|
|
cd contrib/web_ldap
|
|
make depend
|
|
make
|
|
</pre>
|
|
|
|
<h3>Configuration:</h3>
|
|
|
|
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.
|
|
<p>
|
|
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.
|
|
<p><i>
|
|
NOTE: A '#' in the first column of any line
|
|
in the configuration file is considered a comment.
|
|
</i>
|
|
<p>
|
|
The configuration file allows you specify:
|
|
<pre>
|
|
server:
|
|
</pre>
|
|
This is the servername. For example:
|
|
<pre>
|
|
server:ldap.bigfoot.com,389
|
|
</pre>
|
|
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.
|
|
<p>
|
|
Next you will see:
|
|
<pre>
|
|
searchbase:
|
|
</pre>
|
|
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:
|
|
<pre>
|
|
searchbase:c=US
|
|
</pre>
|
|
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:
|
|
<pre>
|
|
searchbase:o=ABC, c=US
|
|
</pre>
|
|
If you want to turn on a simple Debug mode, you can specify any number
|
|
other than zero for 'debug:'. For example:
|
|
<pre>
|
|
debug:1
|
|
</pre>
|
|
turns on the Debug logging mode, and
|
|
<pre>
|
|
debug:0
|
|
</pre>
|
|
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.
|
|
<p>
|
|
The remainder of the configuration file is where you list
|
|
the attributes that you are interested in displaying.
|
|
<p>
|
|
You could list parameters (up to 100) like:
|
|
<pre>
|
|
cn
|
|
givenname
|
|
sn
|
|
</pre>
|
|
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.
|
|
<p>
|
|
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.
|
|
|
|
|
|
<h3>Where to put the files:</h3>
|
|
|
|
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.
|
|
<p>
|
|
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.
|
|
<p>
|
|
Once you have located the cgi-bin (or equivalent) directory,
|
|
put these 2 files there:
|
|
<pre>
|
|
web_ldap
|
|
web_ldap.cfg
|
|
</pre>
|
|
then make sure that these files are accessible to the Web
|
|
Server by executing the Unix shell command:
|
|
<pre>
|
|
> chmod 777 web_ldap*
|
|
</pre>
|
|
Now find the HTML source directory. Copy
|
|
<pre>
|
|
web_ldap.html
|
|
</pre>
|
|
to this directory. Make sure that this file is accessible to the Web
|
|
Server by executing the Unix shell command:
|
|
<pre>
|
|
> chmod 777 web_ldap*
|
|
</pre>
|
|
|
|
<h3>Running the application:</h3>
|
|
|
|
Test it in your own directory by entering:
|
|
<pre>
|
|
> web_ldap DEF
|
|
</pre>
|
|
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:
|
|
<pre>
|
|
<p>++ Error - This script should be referenced with a METHOD of POST.
|
|
</pre>
|
|
as a part of your result with no LDAP data returned.
|
|
<p>
|
|
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'.
|
|
<p>
|
|
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:
|
|
<pre>
|
|
http://my.server.com/cgi-bin/web_ldap
|
|
</pre>
|
|
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.
|
|
<p>
|
|
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').
|
|
<p>
|
|
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'.
|
|
|
|
|
|
<h3>Now that you have it working:</h3>
|
|
|
|
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).
|
|
<p>
|
|
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.
|
|
<p>
|
|
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.
|
|
|
|
|
|
<h3>Usage Information:</h3>
|
|
|
|
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.
|
|
<p>
|
|
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.
|
|
<p>
|
|
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.
|
|
<p>
|
|
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:
|
|
<pre>
|
|
> web_ldap DEF "cn=j*moller"
|
|
|
|
> web_ldap DEF cn=jens moller
|
|
</pre>
|
|
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.
|
|
<p>
|
|
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.
|
|
<p>
|
|
<hr>
|
|
Jens Moller - Jens@colomar.com -
|
|
<a href="http://www.colomar.com">COLOMAR Group</a>.<br>
|
|
|
|
<a href="http://www.OpenLDAP.org/">OpenLDAP</a> - OpenLDAP-devel@OpenLDAP.org.
|