helpers/external_acl/LDAP_group/ext_ldap_group_acl.8

   1 .if !'po4a'hide' .TH ext_ldap_group_acl 8 "30 January 2005"
   2 .
   3 .SH NAME
   4 ext_ldap_group_acl \- Squid LDAP external acl group helper
   5 .PP
   6 Version 2.18
   7 .
   8 .SH SYNOPSIS
   9 .if !'po4a'hide' .B ext_ldap_group_acl
  10 .if !'po4a'hide' .B "\-b \""
  11 base DN
  12 .if !'po4a'hide' .B "\" \-f \""
  13 LDAP search filter
  14 .if !'po4a'hide' .B "\" ["
  15 options
  16 .if !'po4a'hide' .B "] ["
  17 LDAP server name
  18 .if !'po4a'hide' .B "[:"
  19 port
  20 .if !'po4a'hide' .B "]|"
  21 URI
  22 .if !'po4a'hide' .B "]..."
  23 .
  24 .SH DESCRIPTION
  25 .B ext_ldap_group_acl
  26 allows Squid to connect to a LDAP directory to authorize users via LDAP groups.
  27 LDAP options are specified as parameters on the command line,
  28 while the username(s) and group(s) to be checked against the
  29 LDAP directory are specified on subsequent lines of input to the
  30 helper, one username/group pair per line separated by a space.
  31 .PP
  32 As expected by the
  33 .B external_acl_type
  34 construct of Squid, after
  35 specifying a username and group followed by a new line, this
  36 helper will produce either
  37 .B OK
  38 or
  39 .B ERR
  40 on the following line
  41 to show if the user is a member of the specified group.
  42 .PP
  43 The program operates by searching with a search filter based
  44 on the users user name and requested group, and if a match
  45 is found it is determined that the user belongs to the group.
  46 .
  47 .SH OPTIONS
  48 .if !'po4a'hide' .TP 12
  49 .if !'po4a'hide' .BI "\-a " never|always|search|find
  50 When to dereference aliases. Defaults to 'never'
  51 .IP
  52 .BI never
  53 dereference aliases (default),
  54 .BI always
  55 dereference aliases, only while
  56 .BR search ing
  57 or only to
  58 .B find
  59 the base object
  60 .
  61 .if !'po4a'hide' .TP
  62 .if !'po4a'hide' .BI "\-b " "basedn "
  63 .B REQUIRED.
  64 Specifies the base DN under which the groups are located.
  65 .
  66 .if !'po4a'hide' .TP
  67 .if !'po4a'hide' .BI "\-B " "basedn "
  68 Specifies the base DN under which the users are located (if different)
  69 .
  70 .if !'po4a'hide' .TP
  71 .if !'po4a'hide' .BI \-c " connect_timeout"
  72 Specify timeout used when connecting to LDAP servers (requires
  73 Netscape LDAP API libraries)
  74 .
  75 .if !'po4a'hide' .TP
  76 .if !'po4a'hide' .BI \-d
  77 Debug mode where each step taken will get reported in detail.
  78 Useful for understanding what goes wrong if the result is
  79 not what was expected.
  80 .
  81 .if !'po4a'hide' .TP
  82 .if !'po4a'hide' .BI "\-D " "binddn " "\-w " password
  83 The DN and password to bind as while performing searches. Required
  84 if the LDAP directory does not allow anonymous searches.
  85 .IP
  86 As the password needs to be printed in plain text in your Squid configuration
  87 and will be sent on the command line to the helper it is strongly recommended
  88 to use a account with minimal associated privileges.  This to limit the damage
  89 in case someone could get hold of a copy of your Squid configuration file or
  90 extracts the password used from a process listing.
  91 .
  92 .if !'po4a'hide' .TP
  93 .if !'po4a'hide' .BI "\-D " "binddn " "\-W " "secretfile "
  94 The DN and the name of a file containing the password
  95 to bind as while performing searches.
  96 .IP
  97 Less insecure version of the former parameter pair with two advantages:
  98 The password does not occur in the process listing,
  99 and the password is not being compromised if someone gets the squid
 100 configuration file without getting the secretfile.
 101 .
 102 .if !'po4a'hide' .TP
 103 .if !'po4a'hide' .BI \-E certpath
 104 Enable LDAP over SSL (requires Netscape LDAP API libraries)
 105 .
 106 .if !'po4a'hide' .TP
 107 .if !'po4a'hide' .BI "\-f " filter
 108 LDAP search filter used to search the LDAP directory for any
 109 matching group memberships.
 110 .BR
 111 In the filter
 112 .B %u
 113 will be replaced by the user name (or DN if
 114 the
 115 .B \-F
 116 or
 117 .B \-u
 118 options are used) and
 119 .B %g
 120 by the requested group name.
 121 .
 122 .if !'po4a'hide' .TP
 123 .if !'po4a'hide' .BI "\-F " filter
 124 LDAP search filter used to search the LDAP directory for any
 125 matching users.
 126 .BR
 127 In the filter
 128 .B %s
 129 will be replaced by the user name. If
 130 .B %
 131 is to be included literally in the filter then use
 132 .B %%
 133 .
 134 .if !'po4a'hide' .TP
 135 .if !'po4a'hide' .B "\-g"
 136 Specifies that the first query argument sent to the helper by Squid is
 137 a extension to the basedn and will be temporarily added in front of the
 138 global basedn for this query.
 139 .
 140 .if !'po4a'hide' .TP
 141 .if !'po4a'hide' .BI \-h " ldapserver"
 142 Specify the LDAP server to connect to
 143 .
 144 .if !'po4a'hide' .TP
 145 .if !'po4a'hide' .BI \-H " ldapuri"
 146 Specity the LDAP server to connect to by a LDAP URI (requires OpenLDAP libraries)
 147 .
 148 .if !'po4a'hide' .TP
 149 .if !'po4a'hide' .BI \-K
 150 Strip Kerberos Realm component from user names (@ separated)
 151 .
 152 .if !'po4a'hide' .TP
 153 .if !'po4a'hide' .BI \-p " ldapport"
 154 Specify an alternate TCP port where the LDAP server is listening if
 155 other than the default LDAP port 389.
 156 .
 157 .if !'po4a'hide' .TP
 158 .if !'po4a'hide' .BI \-P
 159 Use a persistent LDAP connection. Normally the LDAP connection
 160 is only open while verifying a users group membership to preserve
 161 resources at the LDAP server. This option causes the LDAP connection to
 162 be kept open, allowing it to be reused for further user
 163 validations. Recommended for larger installations.
 164 .
 165 .if !'po4a'hide' .TP
 166 .if !'po4a'hide' .BI \-R
 167 Do not follow referrals
 168 .
 169 .if !'po4a'hide' .TP
 170 .if !'po4a'hide' .BI "-s " base|one|sub
 171 search scope. Defaults to
 172 .B sub
 173 .IP
 174 .B base
 175 object only,
 176 .IP
 177 .B one
 178 level below the base object or
 179 .IP
 180 .BR sub tree
 181 below the base object
 182 .
 183 .if !'po4a'hide' .TP
 184 .if !'po4a'hide' .BI \-S
 185 Strip NT domain name component from user names (/ or \\ separated)
 186 .
 187 .if !'po4a'hide' .TP
 188 .if !'po4a'hide' .BI \-t " search_timeout"
 189 Specify time limit on LDAP search operations
 190 .
 191 .if !'po4a'hide' .TP
 192 .if !'po4a'hide' .BI "\-u " attr
 193 LDAP attribute used to construct the user DN from the user name and
 194 base dn without needing to search for the user.
 195 A maximum of 16 occurrences of
 196 .B %s
 197 are supported.
 198 .
 199 .if !'po4a'hide' .TP
 200 .if !'po4a'hide' .BI \-v " 2|3"
 201 LDAP protocol version. Defaults to
 202 .B 3
 203 if not specified.
 204 .
 205 .if !'po4a'hide' .TP
 206 .if !'po4a'hide' .BI \-Z
 207 Use TLS encryption
 208 .
 209 .SH CONFIGURATION
 210 This helper is intended to be used as an
 211 .B external_acl_type
 212 helper in
 213 .B squid.conf .
 214 .
 215 .if !'po4a'hide' .RS
 216 .if !'po4a'hide' .B external_acl_type ldap_group %LOGIN /path/to/ext_ldap_group_acl ...
 217 .if !'po4a'hide' .br
 218 .if !'po4a'hide' .B acl group1 external ldap_group Group1
 219 .if !'po4a'hide' .br
 220 .if !'po4a'hide' .B acl group2 external ldap_group Group2
 221 .if !'po4a'hide' .RE
 222 .
 223 .PP
 224 .B NOTE:
 225 When constructing search filters it is recommended to first test the filter using
 226 .B ldapsearch
 227 to verify that the filter matches what you expect before you attempt to use
 228 .B ext_ldap_group_acl
 229 .
 230 .SH AUTHOR
 231 This program was written by
 232 .if !'po4a'hide' .I Flavio Pescuma <flavio@marasystems.com>
 233 .if !'po4a'hide' .I Henrik Nordstrom <hno@squid-cache.org>
 234 .PP
 235 Based on prior work in
 236 .B squid_ldap_auth
 237 by
 238 .if !'po4a'hide' .I Glen Newton <glen.newton@nrc.ca>
 239 .PP
 240 This manual was written by
 241 .if !'po4a'hide' .I Henrik Nordstrom <hno@marasystems.com>
 242 .
 243 .SH COPYRIGHT
 244 .PP
 245  * Copyright (C) 1996-2015 The Squid Software Foundation and contributors
 246  *
 247  * Squid software is distributed under GPLv2+ license and includes
 248  * contributions from numerous individuals and organizations.
 249  * Please see the COPYING and CONTRIBUTORS files for details.
 250 .PP
 251 This program and documentation is copyright to the authors named above.
 252 .PP
 253 Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).
 254 .
 255 .SH QUESTIONS
 256 Questions on the usage of this program can be sent to the
 257 .I Squid Users mailing list
 258 .if !'po4a'hide' <squid-users@squid-cache.org>
 259 .PP
 260 Or contact your favorite LDAP list/friend if the question is more related to
 261 LDAP than Squid.
 262 .
 263 .SH REPORTING BUGS
 264 Bug reports need to be made in English.
 265 See http://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.
 266 .PP
 267 Report bugs or bug fixes using http://bugs.squid-cache.org/
 268 .PP
 269 Report serious security bugs to
 270 .I Squid Bugs <squid-bugs@squid-cache.org>
 271 .PP
 272 Report ideas for new improvements to the
 273 .I Squid Developers mailing list
 274 .if !'po4a'hide' <squid-dev@squid-cache.org>
 275 .
 276 .SH SEE ALSO
 277 .if !'po4a'hide' .BR squid "(8), "
 278 .if !'po4a'hide' .BR basic_ldap_auth "(8), "
 279 .if !'po4a'hide' .BR ldapsearch "(1), "
 280 .if !'po4a'hide' .BR GPL "(7), "
 281 .br
 282 Your favorite LDAP documentation
 283 .br
 284 .BR RFC2254 " - The String Representation of LDAP Search Filters,"
 285 .br
 286 The Squid FAQ wiki
 287 .if !'po4a'hide' http://wiki.squid-cache.org/SquidFaq
 288 .br
 289 The Squid Configuration Manual
 290 .if !'po4a'hide' http://www.squid-cache.org/Doc/config/