helpers/external_acl/AD_group/ext_ad_group_acl.8

   1 .if !'po4a'hide' .TH ext_ad_group_acl.exe 8
   2 .
   3 .SH NAME
   4 .if !'po4a'hide' .B ext_ad_group_acl.exe
   5 .if !'po4a'hide' \-
   6 Squid external ACL helper to check Windows users group membership.
   7 .PP
   8 Version 2.0
   9 .
  10 .SH SYNOPSIS
  11 .if !'po4a'hide' .B ext_ad_group_acl.exe
  12 .if !'po4a'hide' .B "[\-D "
  13 domain
  14 .if !'po4a'hide' .B "] [\-cdGh]"
  15 .
  16 .SH DESCRIPTION
  17 .B ext_ad_group_acl.exe
  18 is an installed binary in Squid for Windows builds.
  19 .PP
  20 This helper must be used in with an authentication scheme (typically
  21 Basic, NTLM or Negotiate) based on Windows Active Directory domain users.
  22 .PP
  23 It reads from the standard input the domain username and a list of groups
  24 and tries to match each against the groups membership of the specified
  25 username.
  26 .PP
  27 Two running mode are available:
  28 .if !'po4a'hide' .TP 12
  29 .B "\- Local mode:"
  30 membership is checked against machine's local groups, cannot be used when
  31 running on a Domain Controller.
  32 .PP
  33 .if !'po4a'hide' .TP 12
  34 .B "\- Active Directory Global mode:"
  35 membership is checked against the whole Active Directory Forest of the
  36 machine where Squid is running.
  37 .PP
  38 The minimal Windows version needed to run
  39 .B ext_ad_group_acl.exe
  40 is a Windows 2000 SP4 member of an Active Directory Domain.
  41 .PP
  42 When running in Active Directory Global mode, all types of Active Directory
  43 security groups are supported:
  44 .B "Domain Global"
  45 ,
  46 .B "Domain Local"
  47 from user's domain,
  48 .B "Universal"
  49 and Active Directory group nesting is fully supported.
  50 .
  51 .SH OPTIONS
  52 .if !'po4a'hide' .TP 12
  53 .if !'po4a'hide' .B "\-c"
  54 Use case insensitive compare (local mode only).
  55 .
  56 .if !'po4a'hide' .TP
  57 .if !'po4a'hide' .B "\-d"
  58 Write debug info to stderr.
  59 .
  60 .if !'po4a'hide' .TP
  61 .if !'po4a'hide' .B "\-D" domain
  62 Specify the default user's
  63 .B domain
  64 .
  65 .if !'po4a'hide' .TP
  66 .if !'po4a'hide' .B "\-G"
  67 Start helper in Active Directory Global mode.
  68 .
  69 .if !'po4a'hide' .TP
  70 .if !'po4a'hide' .B "\-h"
  71 Display the binary help and command line syntax info using stderr.
  72 .
  73 .SH CONFIGURATION
  74 .PP
  75 When running in Active Directory Global mode, the AD Group can be specified using the
  76 following syntax:
  77 .
  78 .if !'po4a'hide' .TP 5
  79 .B "1." Plain NT4 Group Name
  80 .
  81 .if !'po4a'hide' .TP
  82 .B "2." Full NT4 Group Name
  83 .
  84 .if !'po4a'hide' .TP
  85 .B "3." Active Directory Canonical name
  86 .
  87 .PP
  88 As Exampled:
  89 .if !'po4a'hide' .TP 5
  90 .if !'po4a'hide' .B "1." Proxy-Users
  91 .
  92 .if !'po4a'hide' .TP
  93 .if !'po4a'hide' .B "2." MYDOMAIN\Proxy-Users
  94 .
  95 .if !'po4a'hide' .TP
  96 .if !'po4a'hide' .B "3." mydomain.local/Groups/Proxy-Users
  97 .PP
  98 When using Plain NT4 Group Name, the Group is searched in the user's domain.
  99 .if !'po4a'hide' .RS
 100 .if !'po4a'hide' .B external_acl_type AD_global_group %LOGIN c:/squid/libexec/ext_ad_group_acl.exe -G
 101 .if !'po4a'hide' .br
 102 .if !'po4a'hide' .B external_acl_type NT_local_group %LOGIN c:/squid/libexec/ext_ad_group_acl.exe
 103 .if !'po4a'hide' .br
 104 .if !'po4a'hide' .br
 105 .if !'po4a'hide' .B "acl GProxyUsers external AD_global_group MYDOMAIN\GProxyUsers"
 106 .if !'po4a'hide' .br
 107 .if !'po4a'hide' .B acl LProxyUsers external NT_local_group LProxyUsers
 108 .if !'po4a'hide' .br
 109 .if !'po4a'hide' .B acl password proxy_auth REQUIRED
 110 .if !'po4a'hide' .br
 111 .if !'po4a'hide' .br
 112 .if !'po4a'hide' .B http_access allow password GProxyUsers
 113 .if !'po4a'hide' .br
 114 .if !'po4a'hide' .B http_access allow password LProxyUsers
 115 .if !'po4a'hide' .br
 116 .if !'po4a'hide' .B http_access deny all
 117 .if !'po4a'hide' .RE
 118 .
 119 .PP
 120 In the previous example all validated AD users member of
 121 .I "MYDOMAIN\GProxyUsers"
 122 domain group or member of
 123 .I LProxyUsers
 124 machine local group are allowed to
 125 use the cache.
 126 .PP
 127 Groups with spaces in name, for example
 128 .B "Domain Users"
 129 , must be quoted and the acl data (
 130 .B "Domain Users"
 131 ) must be placed into a separate file included
 132 by specifying
 133 .B "/path/to/file" .
 134 The previous example will be:
 135 .if !'po4a'hide' .RS
 136 .if !'po4a'hide' acl ProxyUsers external NT_global_group \"c:/squid/etc/DomainUsers\"
 137 .if !'po4a'hide' .RE
 138 and the DomainUsers files will contain only the following line:
 139 .if !'po4a'hide' .RS
 140 "Domain Users"
 141 .if !'po4a'hide' .RE
 142 .
 143 .PP
 144 .B NOTE 1:
 145 When running in Active Directory Global mode, for better performance,
 146 all Domain Controllers of the Active Directory forest should be configured
 147 as Global Catalog.
 148 .
 149 .PP
 150 .B NOTE 2:
 151 When running in local mode, the standard group name comparison is case
 152 sensitive, so group name must be specified with same case as in the
 153 local SAM database.
 154 .
 155 It is possible to enable case insensitive group name comparison (
 156 .B \-c
 157 ),
 158 but on some non\-English locales, the results can be unexpected.
 159 .
 160 .PP
 161 .B NOTE 3:
 162 Native WIN32 NTLM and Basic helpers must be used without the
 163 .B \-A
 164 and
 165 .B \-D
 166 switches.
 167 .
 168 .PP
 169 Refer to Squid documentation for more details on
 170 .B squid.conf
 171 .
 172 .SH TESTING
 173 .PP
 174 I strongly recommend that
 175 .B ext_ad_group_acl.exe
 176 is tested prior to being used in a
 177 production environment. It may behave differently on different platforms.
 178 .
 179 .PP
 180 To test it, run it from the command line. Enter username and group
 181 pairs separated by a space (username must entered with URL-encoded
 182 .I domain%5Cusername
 183 syntax). Press
 184 .B ENTER
 185 to get an
 186 .B OK
 187 or
 188 .B ERR
 189 message.
 190 .PP
 191 Make sure pressing
 192 .B CTRL+D
 193 behaves the same as a carriage return.
 194 .PP
 195 Make sure pressing
 196 .B CTRL+C
 197 aborts the program.
 198 .
 199 .PP
 200 Test that entering no details does not result in an
 201 .B OK
 202 or
 203 .B ERR
 204 message.
 205 .PP
 206 Make sure pressing
 207 .B CTRL+D
 208 behaves the same as a carriage return.
 209 .PP
 210 Make sure pressing
 211 .B CTRL+C
 212 aborts the program.
 213 .
 214 .PP
 215 Test that entering no details does not result in an
 216 .B OK
 217 or
 218 .B ERR
 219 message.
 220 .PP
 221 Test that entering an invalid username and group results in an
 222 .B ERR
 223 message.
 224 .PP
 225 Test that entering an valid username and group results in an
 226 .B OK
 227 message.
 228 .
 229 .SH AUTHOR
 230 This program was written by
 231 .if !'po4a'hide' .I Guido Serassio <guido.serassio@acmeconsulting.it>
 232 .PP
 233 Based on prior work in
 234 .B "mswin_check_lm_group (ext_lm_group_acl)"
 235 .PP
 236 This manual was written by
 237 .if !'po4a'hide' .I Guido Serassio <guido.serassio@acmeconsulting.it>
 238 .if !'po4a'hide' .I Amos Jeffries <amosjeffries@squid-cache.org>
 239 .
 240 .SH COPYRIGHT
 241 .PP
 242  * Copyright (C) 1996-2014 The Squid Software Foundation and contributors
 243  *
 244  * Squid software is distributed under GPLv2+ license and includes
 245  * contributions from numerous individuals and organizations.
 246  * Please see the COPYING and CONTRIBUTORS files for details.
 247 .PP
 248 This program and documentation is copyright to the authors named above.
 249 .PP
 250 Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).
 251 .
 252 .SH QUESTIONS
 253 Questions on the usage of this program can be sent to the
 254 .I Squid Users mailing list
 255 .if !'po4a'hide' <squid-users@squid-cache.org>
 256 .
 257 .SH REPORTING BUGS
 258 Bug reports need to be made in English.
 259 See http://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.
 260 .PP
 261 Report bugs or bug fixes using http://bugs.squid-cache.org/
 262 .PP
 263 Report serious security bugs to
 264 .I Squid Bugs <squid-bugs@squid-cache.org>
 265 .PP
 266 Report ideas for new improvements to the
 267 .I Squid Developers mailing list
 268 .if !'po4a'hide' <squid-dev@squid-cache.org>
 269 .
 270 .SH SEE ALSO
 271 .if !'po4a'hide' .BR squid "(8), "
 272 .if !'po4a'hide' .BR GPL "(7), "
 273 .br
 274 The Squid FAQ wiki
 275 .if !'po4a'hide' http://wiki.squid-cache.org/SquidFaq
 276 .br
 277 The Squid Configuration Manual
 278 .if !'po4a'hide' http://www.squid-cache.org/Doc/config/