Provided by: squid_3.5.12-1ubuntu7_i386 bug

NAME

       basic_ldap_auth - LDAP authentication helper for Squid

SYNOPSIS

       basic_ldap_auth  -b  base DN attribute ] [ options ] [ LDAP server name
       [: port ]| URI ]...
       basic_ldap_auth -b  base DN LDAP search filter options ] [ LDAP  server
       name [: port ]| URI ]...

DESCRIPTION

       basic_ldap_auth allows Squid to connect to a LDAP directory to validate
       the user name and password of Basic HTTP authentication.  LDAP  options
       are  specified as parameters on the command line, while the username(s)
       and password(s) to be checked against the LDAP directory are  specified
       on  subsequent lines of input to the helper, one username/password pair
       per line separated by a space.

       As expected by the  basic  authentication  construct  of  Squid,  after
       specifying  a username and password followed by a new line, this helper
       will produce either OK or ERR on the following  line  to  show  if  the
       specified credentials are correct according to the LDAP directory.

       The  program  has  two major modes of operation. In the default mode of
       operation the users DN is  constructed  using  the  base  DN  and  user
       attribute.  In  the  other mode of operation a search filter is used to
       locate valid user DN's below the base DN.

OPTIONS

       -b basedn   REQUIRED.  Specifies the base DN under which the users  are
                   located.

       -f filter   LDAP  search  filter to locate the user DN. Required if the
                   users are in a hierarchy below the base DN, or if the login
                   name is not what builds the user specific part of the users
                   DN.
                   The search filter can contain up to 15  occurrences  of  %s
                   which  will be replaced by the username, as in  for RFC2037
                   directories. For a  detailed  description  of  LDAP  search
                   filter syntax see RFC2254.
                   Will  crash  if other % values than %s are used, or if more
                   than 15 %s are used.

       -u userattr Specifies the name of the DN attribute  that  contains  the
                   username/login.  Combined with the base DN to construct the
                   users DN when no search filter is specified (  -f  option).
                   Defaults to uid
                   Note:  This  can only be done if all your users are located
                   directly under the same position in the LDAP tree  and  the
                   login  name  is  used  for naming each user object. If your
                   LDAP tree does not match these criterias or if you want  to
                   filter  who  are  valid users then you need to use a search
                   filter to search for your users DN ( -f option).

       -U passwordattr
                   Use ldap_compare instead of ldap_simple_bind to verify  the
                   users password.  passwordattr is the LDAP attribute storing
                   the users password.

       -s base|one|sub
                   Search scope when performing user DN searches specified  by
                   the -f option. Defaults to sub

                   base object only,

                   one level below the base object or

                   subtree below the base object

       -D binddn -w password
                   The  DN  and password to bind as while performing searches.
                   Required by the -f flag if the  directory  does  not  allow
                   anonymous searches.
                   As  the  password needs to be printed in plain text in your
                   Squid configuration it is strongly  recommended  to  use  a
                   account  with minimal associated privileges.  This to limit
                   the damage in case someone could get hold of a copy of your
                   Squid configuration file.

       -D binddn -W secretfile
                   The  DN  and  the name of a file containing the password to
                   bind as while performing searches.
                   Less insecure version of the former parameter pair with two
                   advantages:  The  password  does  not  occur in the process
                   listing, and the  password  is  not  being  compromised  if
                   someone  gets  the squid configuration file without getting
                   the secretfile.

       -P          Use  a  persistent  LDAP  connection.  Normally  the   LDAP
                   connection  is  only  open  while  validating a username to
                   preserve resources at the LDAP server. This  option  causes
                   the  LDAP  connection  to  be  kept open, allowing it to be
                   reused for further user validations. Recommended for larger
                   installations.

       -O          Only  bind  once  per LDAP connection. Some LDAP servers do
                   not allow re-binding as another  user  after  a  successful
                   ldap_bind.   The  use  of  this  option  always opens a new
                   connection for each login attempt. If combined with the  -P
                   option  for  persistent LDAP connection then the connection
                   used for searching for the user DN is kept persistent but a
                   new connection is opened to verify each users password once
                   the DN is found.

       -R          Do not follow referrals

       -a never|always|search|find
                   when to dereference aliases. Defaults to never

                   never dereference  aliases  (default),  always  dereference
                   aliases,  only  while  search  ing or only to find the base
                   object.

       -H ldap_uri Specity the LDAP server to connect to by LDAP URI (requires
                   OpenLDAP libraries).  Servers can also be specified last on
                   the command line.

       -h ldap_server
                   Specify the LDAP server to connect to. Servers can also  be
                   specified last on the command line.

       -p ldap_port
                   Specify  an  alternate  TCP  port  where the LDAP server is
                   listening if other than the default LDAP port 389. Can also
                   be  specified  within  the  server  specification  by using
                   servername:port syntax.

       -v 2|3      LDAP protocol version. Defaults to 3 if not specified.

       -Z          Use TLS encryption

       -S certpath Enable LDAP over SSL (requires Netscape LDAP API libraries)

       -c connect_timeout
                   Specify  timeout  used  when  connecting  to  LDAP  servers
                   (requires Netscape LDAP API libraries)

       -t search_timeout
                   Specify time limit on LDAP search operations

       -d          Debug  mode  where  each  step  taken  will get reported in
                   detail.  Useful for understanding what goes  wrong  if  the
                   results is not what is expected.

CONFIGURATION

       For  directories using the RFC2307 layout with a single domain, all you
       need to specify is usually the base  DN  under  where  your  users  are
       located and the server name:

              basic_ldap_auth -b ou=people,dc=your,dc=domain ldapserver

       If  you  have sub-domains then you need to use a search filter approach
       to locate your user DNs as these can no longer be constructed  directly
       from the base DN and login name alone:

              basic_ldap_auth -b dc=your,dc=domain -f uid=%s ldapserver

       And  similarly  if  you  only  want  to  allow access to users having a
       specific attribute

              basic_ldap_auth         -b         dc=your,dc=domain          -f
              (&(uid=%s)(specialattribute=value)) ldapserver

       Or if the user attribute of the user DN is cn instead of uid and you do
       not want to have to search for the users then you could  use  something
       like the following example for Active Directory:

              basic_ldap_auth -u cn -b cn=Users,dc=your,dc=domain ldapserver

       If you want to search for the user DN and your directory does not allow
       anonymous searches then you must also  use  the  -D  and  -w  flags  to
       specify a user DN and password to log in as to perform the searches, as
       in the following complex Active Directory example

              basic_ldap_auth    -P     -R     -b     dc=your,dc=domain     -D
              cn=squid,cn=users,dc=your,dc=domain  -w  secretsquidpassword  -f
              (&(userPrincipalName=%s)(objectClass=Person))
              activedirectoryserver

       NOTE:  When  constructing  search filters it is strongly recommended to
       test  the  filter  using  ldapsearch  before   you   attempt   to   use
       basic_ldap_auth.   This  to  verify  that  the  filter matches what you
       expect.

AUTHOR

       This program is written by Glenn  Newton  <gnewton@wapiti.cisti.nrc.ca>
       Henrik Nordstrom <hno@squid-cache.org> This manual is written by Henrik
       Nordstrom <hno@squid-cache.org>

COPYRIGHT

        *  Copyright  (C)  1996-2015  The  Squid   Software   Foundation   and
       contributors
        *
        * Squid software is distributed under GPLv2+ license and includes
        * contributions from numerous individuals and organizations.
        * Please see the COPYING and CONTRIBUTORS files for details.

       This program and documentation is copyright to the authors named above.

       Distributed under the GNU General Public License (GNU GPL) version 2 or
       later (GPLv2+).

QUESTIONS

       Questions on the usage of this program can be sent to the  Squid  Users
       mailing list <squid-users@squid-cache.org>

       Or to your favorite LDAP list/friend if the question is more related to
       LDAP than Squid.

REPORTING BUGS

       Bug reports  need  to  be  made  in  English.   See  http://wiki.squid-
       cache.org/SquidFaq/BugReporting for details of what you need to include
       with your bug report.

       Report bugs or bug fixes using http://bugs.squid-cache.org/

       Report serious security bugs to Squid Bugs <squid-bugs@squid-cache.org>

       Report ideas for new improvements to the Squid Developers mailing  list
       <squid-dev@squid-cache.org>

SEE ALSO

       squid(8), ldapsearch(1), GPL(7),
       Your favorite LDAP documentation.
       RFC2254 - The String Representation of LDAP Search Filters,
       The Squid FAQ wiki http://wiki.squid-cache.org/SquidFaq
       The Squid Configuration Manual http://www.squid-cache.org/Doc/config/

                                14 January 2005             basic_ldap_auth(8)