git.sur5r.net Git - openldap/blob - contrib/web_ldap/web_ldap_usage.html

   1 <html>
   2 <title>web_ldap_usage</title>
   3 <body text="#000000"
   4 bgcolor="#FFFFFF">
   5
   6 <h2>web_ldap version 1.1, OpenLDAP variant</h2>
   7
   8 This is an OpenLDAP port of the web_ldap program.
   9 <p>
  10 <i>
  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>.
  19 <p>
  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.
  27 </i>
  28 <h3>Introduction:</h3>
  29
  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.
  37 <p>
  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).
  43 <p>
  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.
  47 <p>
  48 The application can be run interactively (without use of
  49 a Web Browser) but was intended for use as an HTML LDAP Web
  50 page application.
  51 <p>
  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.
  58 <p>
  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.
  64 <p>
  65 The 2 environments are 'Interactive' and 'Web Server'.
  66 <p>
  67 When you execute the application from a command line such as:
  68 <pre>
  69      &gt; web_ldap DEF cn=jens moller
  70 </pre>
  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.
  77 <p>
  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.
  83 <p>
  84 When your program executes from a Web Browser, you will
  85 see something like:
  86 <pre>
  87     http://my.system.com/cgi-bin/web_ldap
  88
  89 </pre>
  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.
  98
  99 <h3>Building the application:</h3>
 100
 101 Requires ISO C (your standard OS compiler or GCC should
 102 work fine).
 103 <p>
 104 Under OpenLDAP, you should build with the following commands after
 105 having configured and built OpenLDAP itself:
 106 <pre>
 107         cd contrib/web_ldap
 108         make depend
 109         make
 110 </pre>
 111
 112 <h3>Configuration:</h3>
 113
 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
 118 from anywhere.
 119 <p>
 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
 123 a different name.
 124 <p><i>
 125 NOTE: A '#' in the first column of any line
 126 in the configuration file is considered a comment.
 127 </i>
 128 <p>
 129 The configuration file allows you specify:
 130 <pre>
 131   server:
 132 </pre>
 133 This is the servername. For example:
 134 <pre>
 135   server:ldap.bigfoot.com,389
 136 </pre>
 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.
 139 <p>
 140 Next you will see:
 141 <pre>
 142   searchbase:
 143 </pre>
 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:
 152 <pre>
 153   searchbase:c=US
 154 </pre>
 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',
 157 you could specify:
 158 <pre>
 159   searchbase:o=ABC, c=US
 160 </pre>
 161 If you want to turn on a simple Debug mode, you can specify any number
 162 other than zero for 'debug:'. For example:
 163 <pre>
 164   debug:1
 165 </pre>
 166 turns on the Debug logging mode, and
 167 <pre>
 168   debug:0
 169 </pre>
 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.
 177 <p>
 178 The remainder of the configuration file is where you list
 179 the attributes that you are interested in displaying.
 180 <p>
 181 You could list parameters (up to 100) like:
 182 <pre>
 183   cn
 184   givenname
 185   sn
 186 </pre>
 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
 196 a value for it.
 197 <p>
 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.
 201
 202
 203 <h3>Where to put the files:</h3>
 204
 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
 208 directory first.
 209 <p>
 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
 214 to Web Server.
 215 <p>
 216 Once you have located the cgi-bin (or equivalent) directory,
 217 put these 2 files there:
 218 <pre>
 219   web_ldap
 220   web_ldap.cfg
 221 </pre>
 222 then make sure that these files are accessible to the Web
 223 Server by executing the Unix shell command:
 224 <pre>
 225   &gt; chmod 777 web_ldap*
 226 </pre>
 227 Now find the HTML source directory. Copy
 228 <pre>
 229   web_ldap.html
 230 </pre>
 231 to this directory. Make sure that this file is accessible to the Web
 232 Server by executing the Unix shell command:
 233 <pre>
 234   &gt; chmod 777 web_ldap*
 235 </pre>
 236
 237 <h3>Running the application:</h3>
 238
 239 Test it in your own directory by entering:
 240 <pre>
 241   &gt; web_ldap DEF
 242 </pre>
 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
 247 error:
 248 <pre>
 249 &lt;p&gt;++ Error - This script should be referenced with a METHOD of POST.
 250 </pre>
 251 as a part of your result with no LDAP data returned.
 252 <p>
 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'.
 257 <p>
 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
 262 to specify the URL:
 263 <pre>
 264   http://my.server.com/cgi-bin/web_ldap
 265 </pre>
 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.
 269 <p>
 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').
 273 <p>
 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'.
 276
 277
 278 <h3>Now that you have it working:</h3>
 279
 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).
 284 <p>
 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.
 290 <p>
 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
 294 against here.
 295
 296
 297 <h3>Usage Information:</h3>
 298
 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.
 304 <p>
 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.
 319 <p>
 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.
 324 <p>
 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:
 328 <pre>
 329   &gt; web_ldap DEF "cn=j*moller"
 330
 331   &gt; web_ldap DEF cn=jens moller
 332 </pre>
 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
 341 need quotes.
 342 <p>
 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.
 349 <p>
 350 <hr>
 351 Jens Moller - Jens@colomar.com -
 352 <a href="http://www.colomar.com">COLOMAR Group</a>.<br>
 353
 354 <a href="http://www.OpenLDAP.org/">OpenLDAP</a> - OpenLDAP-devel@OpenLDAP.org.