]>
Commit | Line | Data |
---|---|---|
0b612336 | 1 | .TH squid_ldap_auth 8 "1 Mars 2003" "Squid LDAP Auth" |
b3def772 | 2 | . |
cfca18fc | 3 | .SH NAME |
4 | squid_ldap_auth - Squid LDAP authentication helper | |
b3def772 | 5 | . |
cfca18fc | 6 | .SH SYNOPSIS |
20b6fc8e | 7 | squid_ldap_auth -b "base DN" [-u attribute] [options] [ldap_server_name[:port]]...] |
b3def772 | 8 | .P |
20b6fc8e | 9 | squid_ldap_auth -b "base DN" -f "LDAP search filter" [options] [ldap_server_name[:port]...] |
b3def772 | 10 | . |
cfca18fc | 11 | .SH DESCRIPTION |
12 | This helper allows Squid to connect to a LDAP directory to | |
13 | validate the user name and password of Basic HTTP authentication. | |
b3def772 | 14 | .P |
15 | The program has two major modes of operation. In the default mode | |
16 | of operation the users DN is constructed using the base DN and | |
17 | user attribute. In the other mode of operation a search | |
18 | filter is used to locate valid user DN's below the base DN. | |
19 | . | |
cfca18fc | 20 | .TP |
21 | .BI "-b " "basedn " (REQUIRED) | |
22 | Specifies the base DN under which the users are located. | |
b3def772 | 23 | . |
cfca18fc | 24 | .TP |
25 | .BI "-f " filter | |
2fd77e91 | 26 | LDAP search filter to locate the user DN. Required if the users |
27 | are in a hierarchy below the base DN, or if the login name is | |
28 | not what builds the user specific part of the users DN. | |
cfca18fc | 29 | .IP |
2fd77e91 | 30 | The search filter can contain up to 15 occurrences of %s |
cfca18fc | 31 | which will be replaced by the username, as in "uid=%s" for |
b3def772 | 32 | RFC2037 directories. For a detailed description of LDAP search |
33 | filter syntax see RFC2254. | |
34 | . | |
cfca18fc | 35 | .TP |
36 | .BI "-u " userattr | |
b3def772 | 37 | Specifies the name of the DN attribute that contains the username/login. |
38 | Combined with the base DN to construct the users DN when no search filter | |
39 | is specified (-f option). Defaults to 'uid' | |
cfca18fc | 40 | .IP |
b3def772 | 41 | Note: This can only be done if all your users are located directly under |
42 | the same position in the LDAP tree and the login name is used for naming | |
43 | each user object. If your LDAP tree does not match these criterias or if | |
44 | you want to filter who are valid users then you need to use a search filter | |
45 | to search for your users DN (-f option). | |
46 | . | |
cfca18fc | 47 | .TP |
48 | .BI "-s " base|one|sub | |
49 | search scope when performing user DN searches specified | |
b3def772 | 50 | by the -f option. Defaults to 'sub'. |
cfca18fc | 51 | .IP |
52 | .B base | |
53 | object only, | |
54 | .B one | |
55 | level below the base object or | |
56 | .BR sub tree | |
57 | below the base object | |
58 | . | |
59 | .TP | |
60 | .BI "-D " "binddn " "-w " password | |
61 | The DN and password to bind as while performing searches. Required by the | |
62 | .BI -f | |
63 | flag if the directory does not allow anonymous searches. | |
64 | .IP | |
65 | As the password needs to be printed in plain text in your Squid configuration | |
2fd77e91 | 66 | it is strongly recommended to use a account with minimal associated privileges. |
cfca18fc | 67 | This to limit the damage in case someone could get hold of a copy of your |
68 | Squid configuration file. | |
b3def772 | 69 | . |
cfca18fc | 70 | .TP |
954a8513 | 71 | .BI "-D " "binddn " "-W " "secretfile " |
72 | The DN and the name of a file containing the password | |
73 | to bind as while performing searches. | |
74 | .IP | |
75 | Less insecure version of the former parameter pair with two advantages: | |
76 | The password does not occur in the process listing, | |
77 | and the password is not being compromised if someone gets the squid | |
78 | configuration file without getting the secretfile. | |
79 | . | |
80 | .TP | |
70c46401 | 81 | .BI -P |
cfca18fc | 82 | Use a persistent LDAP connection. Normally the LDAP connection |
83 | is only open while validating a username to preserve resources | |
84 | at the LDAP server. This option causes the LDAP connection to | |
85 | be kept open, allowing it to be reused for further user | |
86 | validations. Recommended for larger installations. | |
b3def772 | 87 | . |
cfca18fc | 88 | .TP |
89 | .BI -R | |
90 | do not follow referrals | |
b3def772 | 91 | . |
cfca18fc | 92 | .TP |
93 | .BI "-a " never|always|search|find | |
b3def772 | 94 | when to dereference aliases. Defaults to 'never' |
cfca18fc | 95 | .IP |
96 | .BI never | |
97 | dereference aliases (default), | |
98 | .BI always | |
99 | dereference aliases, only while | |
100 | .BR search ing | |
101 | or only to | |
102 | .B find | |
103 | the base object | |
b3def772 | 104 | . |
70c46401 | 105 | .TP |
7ba68818 | 106 | .BI -H " ldapuri" |
653b264e | 107 | Specity the LDAP server to connect to by LDAP URI (requires OpenLDAP libraries) |
7ba68818 | 108 | . |
109 | .TP | |
20b6fc8e | 110 | .BI -h " ldapserver" |
111 | Specify the LDAP server to connect to | |
112 | .TP | |
70c46401 | 113 | .BI -p " ldapport" |
b3def772 | 114 | Specify an alternate TCP port where the ldap server is listening if |
115 | other than the default LDAP port 389. | |
cfca18fc | 116 | . |
653b264e | 117 | .TP |
118 | .BI -Z | |
119 | Use TLS encryption | |
120 | . | |
121 | .TP | |
122 | .BI -S certpath | |
123 | Enable LDAP over SSL (requires Netscape LDAP API libraries) | |
124 | . | |
125 | .TP | |
126 | .BI -c connect_timeout | |
127 | Specify timeout used when connecting to LDAP servers (requires | |
128 | Netscape LDAP API libraries) | |
129 | .TP | |
130 | .BI -t search_timeout | |
131 | Specify time limit on LDAP search operations | |
132 | . | |
cfca18fc | 133 | .SH EXAMPLES |
134 | For directories using the RFC2307 layout with a single domain, all | |
135 | you need to specify is usually the base DN under where your users | |
b3def772 | 136 | are located and the server name: |
cfca18fc | 137 | .IP |
2fd77e91 | 138 | squid_ldap_auth -b ou=people,dc=your,dc=domain ldapserver |
cfca18fc | 139 | .P |
b3def772 | 140 | If you have sub-domains then you need to use a search filter approach |
141 | to locate your user DNs as these can no longer be constructed direcly | |
142 | from the base DN and login name alone: | |
cfca18fc | 143 | .IP |
144 | squid_ldap_auth -b dc=your,dc=domain -f uid=%s ldapserver | |
145 | .P | |
b3def772 | 146 | And similarily if you only want to allow access to users having a |
147 | specific attribute | |
148 | .IP | |
149 | squid_ldap_auth -b dc=your,dc=domain -f (&(uid=%s)(specialattribute=value)) ldapserver | |
150 | .P | |
2fd77e91 | 151 | Or if the user attribute of the user DN is "cn" instead of "uid" and |
152 | you do not want to have to search for the users then you could use something | |
153 | like the following example for Active Directory: | |
cfca18fc | 154 | .IP |
155 | squid_ldap_auth -u cn -b cn=Users,dc=your,dc=domain ldapserver | |
156 | .P | |
2fd77e91 | 157 | If you want to search for the user DN and your directory does not allow |
158 | anonymous searches then you must also use the -D and -w flags to specify | |
159 | a user DN and password to log in as to perform the searches, as in the | |
160 | following complex Active Directory example | |
cfca18fc | 161 | .IP |
b3def772 | 162 | squid_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 |
163 | . | |
164 | .SH NOTES | |
165 | . | |
166 | When constructing search filters it is strongly recommended to test the filter | |
167 | using ldapsearch before you attempt to use squid_ldap_auth. This to verify | |
168 | that the filter matches what you expect. | |
cfca18fc | 169 | . |
170 | .SH AUTHOR | |
171 | This manual page was written by | |
172 | .I Henrik Nordstrom <hno@squid-cache.org> | |
173 | .P | |
174 | squid_ldap_auth is written by | |
175 | .I Glenn Newton <gnewton@wapiti.cisti.nrc.ca> | |
176 | and | |
177 | .I Henrik Nordstrom <hno@squid-cache.org> | |
178 | . | |
179 | .SH KNOWN ISSUES | |
180 | Will crash if other % values than %s is used in -f, or if more than 15 %s | |
181 | is used. | |
182 | . | |
183 | .SH QUESTIONS | |
184 | Any questions on usage can be sent to | |
185 | .IR "Squid Users <squid-users@squid-cache.org>" , | |
b3def772 | 186 | or to your favorite LDAP list/friend if the question is more related to |
187 | LDAP than Squid. | |
cfca18fc | 188 | . |
189 | .SH REPORTING BUGS | |
190 | Report bugs or bug-fixes to | |
b3def772 | 191 | .I Squid Bugs <squid-bugs@squid-cache.org> |
192 | or ideas for new improvements to | |
cfca18fc | 193 | .I Squid Developers <squid-dev@squid-cache.org> |
b3def772 | 194 | . |
b3def772 | 195 | .SH "SEE ALSO" |
196 | .BR ldapsearch ( 1 ), | |
197 | .br | |
198 | Your favorite LDAP documentation | |
199 | .br | |
200 | .BR RFC2254 " - The String Representation of LDAP Search Filters," |