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