src/acl/external/AD_group/ext_ad_group_acl.8

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