helpers/external_acl/kerberos_ldap_group/ext_kerberos_ldap_group_acl.8

   1 .if !'po4a'hide' .TH ext_kerberos_ldap_group_acl 8
   2 .
   3 .SH NAME
   4 .if !'po4a'hide' .B ext_kerberos_ldap_group_acl
   5 .if !'po4a'hide' \-
   6 Squid LDAP external acl group helper for Kerberos or NTLM credentials.
   7 .PP
   8 Version 1.3.0sq
   9 .
  10 .SH SYNOPSIS
  11 .if !'po4a'hide' .B ext_kerberos_ldap_group_acl
  12 .if !'po4a'hide' .B [\-h] [\-d] [\-i] [\-s] [\-a] [\-D Realm ] [\-N Netbios-Realm-List] [\-m Max-Depth] [\-u Ldap-User] [\-p Ldap-Password] [\-b Ldap-Bind-Path] [\-l Ldap-URL] [\-S ldap server list] \-g Group-Realm-List \-t  Hex-Group-Realm-List \-T Hex-Group-Hex-Realm-List
  13 .
  14 .SH DESCRIPTION
  15 .B ext_kerberos_ldap_group_acl
  16 is an installed binary and allows Squid to connect to a LDAP directory to
  17 authorize users via LDAP groups. Options are specified as parameters on the
  18 command line, while the username (e.g.
  19 .B user
  20 ,
  21 .B user@REALM
  22 ,
  23 .B NDOMAIN\\user
  24 ) to be checked against the LDAP directory are specified on subsequent lines of
  25 input to the helper, one username per line.
  26 .PP
  27 .B ext_kerberos_ldap_group_acl
  28 will determine the ldap server name from DNS SRV and/or A records or a
  29 local hosts file (e.g. for the Kerberos Realm
  30 .B SUSE.HOME
  31 it will look for an SRV record
  32 .B _ldap._tcp.SUSE.HOME
  33 and an A record
  34 .B SUSE.HOME
  35 or a
  36 .B SUSE.HOME
  37 hosts entry). If no domain information is available from the
  38 username the LDAP server will be determined through the command line options.
  39 .PP
  40 .B ext_kerberos_ldap_group_acl
  41 requires as a minimum the
  42 .B \-g
  43 ,
  44 .B \-t
  45 or
  46 .B \-T
  47 option which provides the LDAP group name the user has to belong too. For Active Directory
  48 a recursive group lookup is implemented until a max depth specified by
  49 .B \-m
  50 depth. For other LDAP servers a RFC2307bis schema of groups is assumed.
  51 .PP
  52 Different group names can be specified for different domains using a
  53 group@domain syntax.
  54 As expected by the
  55 .B external_acl_type
  56 construct of Squid, after
  57 specifying a username and group followed by a new line, this
  58 helper will produce either
  59 .B OK
  60 or
  61 .B ERR
  62 on the following line
  63 to show if the user is a member of the specified group.
  64 .
  65 .SH OPTIONS
  66 .if !'po4a'hide' .TP 12
  67 .if !'po4a'hide' .B \-h
  68 Display the binary help and command line syntax info using stderr.
  69 .if !'po4a'hide' .TP 12
  70 .if !'po4a'hide' .B \-d
  71 Write debug messages to stderr.
  72 .if !'po4a'hide' .TP 12
  73 .if !'po4a'hide' .B \-i
  74 Write informational messages to stderr.
  75 .if !'po4a'hide' .TP 12
  76 .if !'po4a'hide' .B \-s
  77 Use SSL for the LDAP connection.
  78 .IP
  79 The CA certificate file can be set via the environment variable TLS_CACERTFILE (default /etc/ssl/certs/cert.pem) (OpenLDAP).
  80 .IP
  81 The SSL certificate database can be set via the environment variable SSL_CERTDBPATH (default /etc/certs) (Sun and Mozilla LDAP SDK).
  82 .if !'po4a'hide' .TP 12
  83 .if !'po4a'hide' .B \-a
  84 Allow SSL without certificate verification.
  85 .if !'po4a'hide' .TP 12
  86 .if !'po4a'hide' .B \-D Realm
  87 Default Kerberos domain to use for usernames which do not contain domain
  88 information (e.g. for users using basic authentication).
  89 .if !'po4a'hide' .TP 12
  90 .if !'po4a'hide' .B \-N Netbios-Realm-List
  91 A list of Netbios name mappings to Kerberos domain names of the form
  92 Netbios-Name@Kerberos-Realm[:Netbios-Name@Kerberos-Realm] (e.g. for users
  93 using NTLM authentication).
  94 .if !'po4a'hide' .TP 12
  95 .if !'po4a'hide' .B \-m Max-Depth
  96 Maximal depth of recursive group search.
  97 .if !'po4a'hide' .TP 12
  98 .if !'po4a'hide' .B \-u Ldap-User
  99 Username for LDAP server.
 100 .if !'po4a'hide' .TP 12
 101 .if !'po4a'hide' .B \-u Ldap-Password
 102 Password for LDAP server.
 103 .IP
 104 As the password needs to be printed in plain text in your Squid configuration
 105 it is strongly recommended to use an account with minimal associated privileges.
 106 This to limit the damage in case someone could get hold of a copy of your Squid
 107 configuration file or extracts the password used from a process listing.
 108 .
 109 .if !'po4a'hide' .TP 12
 110 .if !'po4a'hide' .B \-b Ldap-Bind-Path
 111 LDAP server bind path.
 112 .if !'po4a'hide' .TP 12
 113 .if !'po4a'hide' .B \-u Ldap-URL
 114 LDAP server URL in form ldap[s]://server:port
 115 .if !'po4a'hide' .TP 12
 116 .if !'po4a'hide' .B \-S ldap server list
 117 list of ldap servers of the form
 118 lserver|lserver@|lserver@Realm[:lserver@|lserver@Realm]
 119 .if !'po4a'hide' .TP 12
 120 .if !'po4a'hide' .B \-g Group-Realm-List
 121 A list of group name per Kerberos domain of the form
 122 Group|Group@|Group@Realm[:Group@|Group@Realm]
 123 .if !'po4a'hide' .TP 12
 124 .if !'po4a'hide' .B \-t  Hex-Group-Realm-List
 125 A list of group name per Kerberos domain of the
 126 form Group|Group@|Group@Realm[:Group@|Group@Realm] where group is in
 127 UTF-8 hex format
 128 .if !'po4a'hide' .TP 12
 129 .if !'po4a'hide' .B \-T Hex-Group-Hex-Realm-List
 130 A list of group name per Kerberos domain of the form
 131 Group|Group@|Group@Realm[:Group@|Group@Realm] where group and domain
 132 is in UTF-8 hex format
 133 .
 134 .SH CONFIGURATION
 135 .PP
 136 This helper is intended to be used as an
 137 .B external_acl_type
 138 helper in
 139 .B squid.conf.
 140 .if !'po4a'hide' .P
 141 .if !'po4a'hide' .ft CR
 142 .if !'po4a'hide' .nf
 143 .if !'po4a'hide' external_acl_type kerberos_ldap_group1  ttl=3600  negative_ttl=3600 %LOGIN /path/to/ext_kerberos_ldap_group_acl -g GROUP1
 144 .if !'po4a'hide' .br
 145 .if !'po4a'hide' external_acl_type kerberos_ldap_group2  ttl=3600  negative_ttl=3600 %LOGIN /path/to/ext_kerberos_ldap_group_acl -g GROUP2
 146 .if !'po4a'hide' .br
 147 .if !'po4a'hide' acl group1 external kerberos_ldap_group1
 148 .if !'po4a'hide' .br
 149 .if !'po4a'hide' acl group2 external kerberos_ldap_group2
 150 .if !'po4a'hide' .fi
 151 .if !'po4a'hide' .ft
 152 .PP
 153 .B NOTE:
 154 The following squid startup file modification may be required:
 155 .
 156 Add the following lines to the squid startup script to point squid to a keytab file which
 157 contains the HTTP/fqdn service principal for the default Kerberos domain. The fqdn must be
 158 the proxy name set in IE or firefox. You can not use an IP address.
 159 .if !'po4a'hide' .P
 160 .if !'po4a'hide' .ft CR
 161 .if !'po4a'hide' .nf
 162 .if !'po4a'hide' KRB5_KTNAME=/etc/squid/HTTP.keytab
 163 .if !'po4a'hide' export KRB5_KTNAME
 164 .if !'po4a'hide' .fi
 165 .if !'po4a'hide' .ft
 166 .
 167 If you use a different Kerberos domain than the machine itself is in you can point squid to
 168 the seperate Kerberos config file by setting the following environmnet variable in the startup
 169 script.
 170 .if !'po4a'hide' .P
 171 .if !'po4a'hide' .ft CR
 172 .if !'po4a'hide' .nf
 173 .if !'po4a'hide' KRB5_CONFIG=/etc/krb5-squid.conf
 174 .if !'po4a'hide' export KRB5_CONFIG
 175 .if !'po4a'hide' .fi
 176 .if !'po4a'hide' .ft
 177 .
 178 .B ext_kerberos_ldap_group_acl
 179 will determine automagically the right ldap server. The following method is used:
 180
 181 1) For user@REALM
 182    a) Query DNS for SRV record _ldap._tcp.REALM
 183    b) Query DNS for A record REALM
 184    c) Use LDAP_URL if given
 185
 186 2) For user
 187    a) Use domain -D REALM and follow step 1)
 188    b) Use LDAP_URL if given
 189
 190 The Groups to check against are determined as follows:
 191
 192 1) For user@REALM
 193    a) Use values given by -g option which contain a @REALM e.g. -g GROUP1@REALM:GROUP2@REALM
 194    b) Use values given by -g option which contain a @ only e.g. -g GROUP1@:GROUP2@
 195    c) Use values given by -g option which do not contain a realm e.g. -g GROUP1:GROUP2
 196
 197 2) For user
 198    a) Use values given by -g option which do not contain a realm e.g. -g GROUP1:GROUP2
 199
 200 3) For NDOMAIN\\user
 201    a) Use realm given by -N NDOMAIN@REALM and then use values given by -g option which contain a @REALM e.g. -g GROUP1@REALM:GROUP2@REALM
 202
 203 To support Non-ASCII character use -t GROUP  or -t GROUP@REALM instead of -g where GROUP is the hex UTF-8 representation e.g.
 204
 205    -t 6d61726b7573 instead of -g markus
 206
 207 The REALM must still be based on the ASCII character set. If REALM contains also non ASCII characters use -T GROUP@REALM where GROUP and REALM are hex UTF-8 representation e.g.
 208
 209   -T 6d61726b7573@57494e3230303352322e484f4d45 instead of -g markus@WIN2003R2.HOME
 210
 211 For a translation of hex UTF-8 see for example http://www.utf8-chartable.de/unicode-utf8-table.pl
 212
 213 The ldap server list can be:
 214 server - In this case server can be used for all Kerberos domains
 215 server@  - In this case server can be used for all Kerberos domains
 216 server@domain  - In this case server can be used for Kerberos domain domain
 217 server1a@domain1:server1b@domain1:server2@domain2:server3@:server4 - A list is build with a colon as seperator
 218
 219 .
 220 .SH AUTHOR
 221 This program was written by
 222 .if !'po4a'hide' .I Markus Moeller <markus_moeller@compuserve.com>
 223 .PP
 224 This manual was written by
 225 .if !'po4a'hide' .I Markus Moeller <markus_moeller@compuserve.com>
 226 .
 227 .SH COPYRIGHT
 228 This program and documentation is copyright to the authors named above.
 229 .PP
 230 Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).
 231 .
 232 .SH QUESTIONS
 233 Questions on the usage of this program can be sent to the
 234 .I Squid Users mailing list
 235 .if !'po4a'hide' <squid-users@squid-cache.org>
 236 .
 237 .SH REPORTING BUGS
 238 Bug reports need to be made in English.
 239 See http://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.
 240 .PP
 241 Report bugs or bug fixes using http://bugs.squid-cache.org/
 242 .PP
 243 Report serious security bugs to
 244 .I Squid Bugs <squid-bugs@squid-cache.org>
 245 .PP
 246 Report ideas for new improvements to the
 247 .I Squid Developers mailing list
 248 .if !'po4a'hide' <squid-dev@squid-cache.org>
 249 .
 250 .SH SEE ALSO
 251 .if !'po4a'hide' .BR squid "(8) "
 252 .if !'po4a'hide' .BR negotiate_kerberos_auth "(8) "
 253 .br
 254 .BR RFC1035 " - Domain names - implementation and specification,"
 255 .br
 256 .BR RFC2782 " - A DNS RR for specifying the location of services (DNS SRV),"
 257 .br
 258 .BR RFC2254 " - The String Representation of LDAP Search Filters,"
 259 .br
 260 .BR RFC2307bis " - An Approach for Using LDAP as a Network Information Service
 261 http://www.padl.com/~lukeh/rfc2307bis.txt,"
 262 .br
 263 The Squid FAQ wiki
 264 .if !'po4a'hide' http://wiki.squid-cache.org/SquidFaq
 265 .br
 266 The Squid Configuration Manual
 267 .if !'po4a'hide' http://www.squid-cache.org/Doc/config/