<?xml version="1.0" ?>
<?xml-stylesheet href="faq.xsl" type="text/xsl"?>
<!DOCTYPE faq SYSTEM "faq.dtd"
[
<!ENTITY al "<auth_ldap/>">
]
>
<!--
      Copyright (c) 2000,2001 Dave Carrigan <dave@rudedog.org>
      All rights reserved.
      
      $Id: faq.xml,v 1.9 2001/07/04 14:40:37 dave Exp $
      Source: $Source: /var/cvs/src/auth_ldap/faq.xml,v $
-->

<faq>
  <intro>
    <para>
      Here is a list of frequently asked questions (and answers) for
      &al;. More questions and answers can be found on the &al; mailing
      list, at <link
      url="http://www.rudedog.org/auth_ldap/">http://www.rudedog.org/auth_ldap/</link>.
    </para>
  </intro>

  <qa 
      class="runtime" 
      title="auth_ldap Asks for Authentication Twice"
      name="double">
    <q>
      <para>
	&al; is working, but the first time I load a page, it asks for
	authentication twice.
      </para>
    </q>
    <a>
      <para>
	This is not really an &al; problem. It usually happens when
	Apache authenticates a client, then sends the client a
	redirect. The client thinks that the redirected page is not in
	the same realm as the page it already provided credentials for,
	so it doesn't send the credentials when it does its new request,
	causing Apache to ask for credentials again. This is most common
	when the first URL was for a directory, but didn't include the
	trailing slash. For more information, see 
	<link url="http://www.apache.org/docs/misc/FAQ.html#prompted-twice">
	  the Apache FAQ</link>. 
      </para>
    </a>
  </qa>

  <qa class="load" title="Undefined Symbols for LoadModule" name="misslibs">
    <q>
      <para>
	The module compiled fine, but when Apache tries to load it, I
	get the message
      </para>
      <error><![CDATA[
Syntax error on line 202 of /opt/apache/conf/httpd.conf:
Cannot load /opt/apache/libexec/auth_ldap.so into server:
/opt/apache/libexec/auth_ldap.so: undefined symbol: ldap_foo_bar
/opt/apache/bin/apachectl start: httpd could not be started ]]>
      </error>
    </q>
    <a>
      <para>
	Apache is not finding the LDAP shared libraries. This is very
	common if the libraries are not put into <file>/usr/lib</file>
	or some other directory that the shared loader automatically
	searches.
      </para>

      <para>
	On Solaris, you can
	supply the runtime search path at link time by adding 
	<verbatim>-R/path/to/ldap/libdir</verbatim> to
	<verbatim>LIBS</verbatim> in the <file>Makefile</file>. 
      </para>

      <para>
	On Linux, you could add the path to
	<file>/etc/ld.so.conf</file>, or you could add
	<verbatim>-Wl,-rpath,/path/to/ldap/libdir</verbatim> to
	<verbatim>LIBS</verbatim> in the <file>Makefile</file>.
      </para>

      <para>
	Other operating systems probably have similar solutions.
      </para>

      <para>
	Note that <command>configure</command> will <emph>not</emph>
	figure this out for you. If you need to have these extra flags,
	then invoke <command>configure</command> with extra values for
	<verbatim>LDFLAGS</verbatim>. For example, under Linux, you
	would run

      </para> 
      <para>
	<verbatim>
	  LDFLAGS='-Wl,-rpath,/path/to/ldap/libdir' ./configure --option ...
	</verbatim>
      </para>

    </a>
  </qa>

  <qa 
      class="load" 
      title="Incompatible Module after Apache Upgrade"
      name="upgrade">
    <q>
      <para>
	&al; was working fine under my old version of Apache, but now
	that we've upgraded Apache, &al; doesn't work any more. Apache
	says that the module is incompatible with this version of Apache.
      </para>
    </q>
    <a>
      <para>
	Whenever you upgrade Apache, you usually have to re-compile all
	of your extra Apache modules. Apache makes no guarantees that a
	module will be binary-compatible between releases. Modules are
	usually source-compatible between releases, and &al; is known to
	work with all of the 3.x versions of Apache.
      </para>
    </a>
  </qa>

  <qa 
      class="runtime" 
      title="AuthType (or AuthName) Not Set"
      name="authtype">
    <q>
      <para>
	&al; loads fine, but when I try to protect a directory, it
	doesn't work. The Apache logs say <error>Couldn't perform
	authentication. AuthType not set!</error>
      </para>
    </q>
    <a>
      <para>
	You need to provide both the <directive>AuthType</directive>
	and <directive>AuthName</directive> directives. These are
	standard Apache directives, and are required for any
	authentication module. 
      </para>
    </a>
  </qa>

  <qa 
      class="load" 
      title="Apache Doesn't Recognize Any auth_ldap Directives"
      name="unloadmod">
    <q>
      <para>
	The module builds fine, and the
	<directive>LoadModule</directive> works OK, but if I try to use
	some &al; directives, I get the following error:
      </para>
      <error>
Syntax error on line 937 of /etc/httpd/conf/httpd.conf:
Invalid command 'AuthLDAPURL', perhaps mis-spelled or defined by a
  module not included in the server configuration
      </error>
    </q>
    <a>
      <para>
	It's possible that you have a
	<directive>ClearModuleList</directive> directive in your Apache
	configuration. If so, you will also need a <directive>AddModule
	  auth_ldap.c</directive> directive. The default
	  <file>httpd.conf</file>
	file that is distributed with Apache usually does have the
	<directive>ClearModuleList</directive> directive, so this is
	very likely to occur if your Apache configuration is based on
	the distributed one.
      </para>
    </a>
  </qa>

  <qa class="compile" title="Where is ldap_ssl.h?" name="ldap_ssl">
    <q>
      <para>
	During compilation, it wants <file>ldap_ssl.h</file>. Where can
	I find this file?
      </para>
    </q>
    <a>
      <para>
	This file comes with the Netscape SDK. OpenLDAP doesn't support
	SSL, so if you're using OpenLDAP, then make sure that you've
	commented out the <verbatim>SSL=-DWITH_SSL</verbatim> line in
	the <file>Makefile</file>.
      </para>
    </a>
  </qa>

  <qa 
      class="misc" 
      title="Can I Pass the LDAP Password to a CGI Program?" 
      name="ldappasswd">
    <q>
      <para>
	How can I pass the LDAP password to a CGI program?
      </para>
    </q>
    <a>
      <para>
	The short answer is that you can't. 
      </para>

      <para>
	The long answer is that there are a couple of ways to do this,
	but enabling this can cause an extremely big security hole on
	your server unless you completely understand the implications of
	what you're about to do.
      </para>

      <para>
	First, Apache has an un-documented compile-time option that will
	cause it to pass the <verbatim>Authorization</verbatim> header
	to CGI programs, so if you absolutely feel that you need this,
	you should read the Apache source and re-compile Apache.
      </para>

      <para>
	Some embedded scripting languages, such as
	<link url="http://perl.apache.org/">
	  <command>mod_perl</command></link> and
	<link url="http://www.php.net/">
	  <command>PHP</command></link>, provide you with access to all
	of Apache's internal variables, so you could also use these to
	access the password. If you are already using Perl CGI programs,
	then it would be fairly easy to migrate them to
	<command>mod_perl</command> using
	<command>Apache::Registry</command>.
      </para>

      <para>
	I have had a lot of requests for this feature (and even a couple
	of patches), but I am loathe to add this to &al; because it adds
	one more potential vulnerability to the Apache server, and it
	would further complicate any security audit. Since there are
	already multiple mechanisms available to to access the password,
	I don't believe that adding another one to &al; would be
	appropriate.
      </para>
    </a>
  </qa>

  <qa 
      class="load" 
      title="Undefined Symbol: pthread_create"
      name="pthread">
    <q>
      <para>
	&al; compiles fine, but when I try to load it with the
	<directive>LoadModule</directive> directive, Apache complains
	with the error <error>undefined symbol:
	pthread_create</error>. I'm using the Netscape SDK on Linux.
      </para>
    </q>
    <a>
      <para>
	You have to add <verbatim>-lpthread</verbatim> to
	<verbatim>LIBS</verbatim> in the <file>Makefile</file>.
      </para>
    </a>
  </qa>

  <qa 
      class="compile" 
      title="Compile Dies with Error About __builtin_va_alist" 
      name="valist">
    <q>
      <para>
	I'm trying to compile &al; with GCC on a Solaris system, and the
	compile dies with
      </para>
      <error>
auth_ldap.c: In function `auth_ldap_log_reason':
auth_ldap.c:130: `__builtin_va_alist' undeclared (first use in this
function)
auth_ldap.c:130: (Each undeclared identifier is reported only once
auth_ldap.c:130: for each function it appears in.)
*** Error code 1
make: Fatal error: Command failed for target `auth_ldap.o'
Exit 1
      </error>
    </q>
    <a>
      <para>
	&al; is being compiled with the
	<verbatim>-I/usr/include</verbatim> option. Figure out why, and
	get rid of it. Compiling with
	<verbatim>-I/usr/include</verbatim> and GCC causes GCC's varargs
	to barf.
      </para>
    </a>
  </qa>

  <qa class="runtime" title="Cannot Parse LDAP URL" name="cantparse">
    <q>
      <para>
	I'm using &al; with OpenLDAP, and when it starts, I get the
	error message <error>Cannot parse LDAP URL</error>. The URL
	looks fine to me.
      </para>
    </q>
    <a>
      <para>
	The exact cause of this problem is not yet known, but it appears
	to be some kind of strange interaction with Apache and
	OpenLDAP. Make sure that you have the latest versions of each.
      </para>
    </a>
  </qa>

  <qa 
      class="compile" 
      title='Compile Dies With "-o: not found"'
      name="apxsprob">
    <q>
      <para>
	I'm trying to compile &al; and I get the following output
      </para>
      <error>
gcc -c -o auth_ldap.o -DSOLARIS2=270 -DUSE_EXPAT -I../lib/expat-lite
-Wall -I/usr/local/apache/include -I/disk/SDK/include auth_ldap.c
gcc -c -o auth_ldap_config.o -DSOLARIS2=270 -DUSE_EXPAT
-I../lib/expat-lite -Wall -I/usr/local/apache/include
-I/disk/SDK/include auth_ldap_config.c
gcc -c -o auth_ldap_cache.o -DSOLARIS2=270 -DUSE_EXPAT
-I../lib/expat-lite -Wall -I/usr/local/apache/include
-I/disk/SDK/include auth_ldap_cache.c
-o auth_ldap.so auth_ldap.o auth_ldap_config.o auth_ldap_cache.o
-lldapssl40
/bin/sh: -o: not found
make: *** [auth_ldap.so] Error 1
      </error>
    </q>
    <a>
      <para>
	This is typically caused when Apache hasn't been compiled with
	dynamic module (<file>mod_so</file>) support. The output of the
	command <command>apxs -q LD_SHLIB</command> is blank, when it
	should print the name of the loader program to use (usually
	<program>ld</program>). If you're sure that your Apache has been
	built with <file>mod_so</file>, you should try to rebuild Apache
	from a clean build tree. I have seen instances where the
	<file>apxs</file> command was out of date with respect to the
	real Apache configuration, and a clean rebuild fixed it.
      </para>
    </a>
  </qa>

  <qa 
      class="load" 
      title="Apache Crashes with a Segfault"
      name="segfault">
    <q>
      <para>
	Apache crashes with a segfault. 
      </para>
    </q>
    <a>
      <para>
	One situation where I've seen this is if you are using PHP with
	LDAP support and PHP is linked against one LDAP SDK, while &al;
	is linked against a different LDAP SDK. 
      </para>
    </a>
  </qa>

  <qa 
      class="runtime" 
      title="Some DNs Don't Match with the require group Directive" 
      name="dnsyntax">
    <q>
      <para>
	The <directive>require group</directive> directive only works if
	the spaces in the user's DN exactly match the spaces for the
	<verbatim>uniquemember</verbatim> attribute in the group
	entry. I thought spaces didn't matter in distinguished names?
	I'm using OpenLDAP.
      </para>
    </q>
    <a>
      <para>
	OpenLDAP doesn't define the <verbatim>uniquemember</verbatim>
	attribute. If an attribute is not defined in OpenLDAP, it
	defaults to having CIS syntax. With DN syntax, differing
	whitespace is considered equal in an LDAP compare, but with CIS
	syntax, differing whitespace is considered different. You will
	have to add <verbatim>uniquemember</verbatim> to your
	<file>slapd.at.conf</file> file.
      </para>
    </a>
  </qa>
</faq>
