]>
Commit | Line | Data |
---|---|---|
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 | filter | |
14 | .if !'po4a'hide' .B "[" | |
15 | options | |
16 | .if !'po4a'hide' .B "] [" | |
17 | server | |
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 during a | |
56 | .BR search | |
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 | Specify 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-2018 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@lists.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@lists.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@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 | |
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/ |