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