"program" cmdline
Specify the command for the external authenticator. Such a program
- reads a line containing "username password" and replies "OK" or
- "ERR" in an endless loop. "ERR" responses may optionally be followed
- by a error description available as %m in the returned error page.
+ reads a line containing "username password" and replies with one of
+ three results:
+
+ OK
+ the user exists.
+
+ ERR
+ the user does not exist.
+
+ BH
+ An internal error occured in the helper, preventing
+ a result being identified.
+
+ "ERR" and "BH" results may optionally be followed by message="..."
+ containing a description available as %m in the returned error page.
+
If you use an authenticator, make sure you have 1 acl of type
proxy_auth.
"program" cmdline
Specify the command for the external authenticator. Such
a program reads a line containing "username":"realm" and
- replies with the appropriate H(A1) value hex encoded or
- ERR if the user (or his H(A1) hash) does not exists.
- See rfc 2616 for the definition of H(A1).
- "ERR" responses may optionally be followed by a error description
- available as %m in the returned error page.
+ replies with one of three results:
+
+ OK ha1="..."
+ the user exists. The ha1= key is mandatory and
+ contains the appropriate H(A1) value, hex encoded.
+ See rfc 2616 for the definition of H(A1).
+
+ ERR
+ the user does not exist.
+
+ BH
+ An internal error occured in the helper, preventing
+ a result being identified.
+
+ "ERR" and "BH" results may optionally be followed by message="..."
+ containing a description available as %m in the returned error page.
By default, the digest authentication scheme is not used unless a
program is specified.
Such a program reads exchanged NTLMSSP packets with
the browser via Squid until authentication is completed.
If you use an NTLM authenticator, make sure you have 1 acl
- of type proxy_auth. By default, the NTLM authenticator_program
+ of type proxy_auth. By default, the NTLM authenticator program
is not used.
auth_param ntlm program @DEFAULT_PREFIX@/bin/ntlm_auth
using the Kerberos mechanisms.
If you use a Negotiate authenticator, make sure you have at least
one acl of type proxy_auth active. By default, the negotiate
- authenticator_program is not used.
+ authenticator program is not used.
The only supported program for this role is the ntlm_auth
program distributed as part of Samba, version 4 or later.
%% The percent sign. Useful for helpers which need
an unchanging input format.
- In addition to the above, any string specified in the referencing
- acl will also be included in the helper request line, after the
- specified formats (see the "acl external" directive)
- The helper receives lines per the above format specification,
- and returns lines starting with OK or ERR indicating the validity
- of the request and optionally followed by additional keywords with
- more details.
+ General request syntax:
+
+ [channel-ID] FORMAT-values [acl-values ...]
+
+
+ FORMAT-values consists of transaction details expanded with
+ whitespace separation per the config file FORMAT specification
+ using the FORMAT macros listed above.
+
+ acl-values consists of any string specified in the referencing
+ config 'acl ... external' line. see the "acl external" directive.
+
+ Request values sent to the helper are URL escaped to protect
+ each value in requests against whitespaces.
+
+ If using protocol=2.5 then the request sent to the helper is not
+ URL escaped to protect against whitespace.
+
+ NOTE: protocol=3.0 is deprecated as no longer necessary.
+
+ When using the concurrency= option the protocol is changed by
+ introducing a query channel tag in front of the request/response.
+ The query channel tag is a number between 0 and concurrency-1.
+ This value must be echoed back unchanged to Squid as the first part
+ of the response relating to its request.
+
+
+ The helper receives lines expanded per the above format specification
+ and for each input line returns 1 line starting with OK/ERR/BH result
+ code and optionally followed by additional keywords with more details.
+
General result syntax:
- [channel-ID] OK/ERR/BH keyword=value ...
+ [channel-ID] result keyword=value ...
+
+ Result consists of one of the codes:
+
+ OK
+ the ACL test produced a match.
+
+ ERR
+ the ACL test does not produce a match.
+
+ BH
+ An internal error occured in the helper, preventing
+ a result being identified.
+
+ The meaning of 'a match' is determined by your squid.conf
+ access control configuration. See the Squid wiki for details.
Defined keywords:
user= The users name (login)
+
password= The users password (for login= cache_peer option)
+
message= Message describing the reason for this response.
- Available as %o in error pages. Useful on (ERR and BH results).
+ Available as %o in error pages.
+ Useful on (ERR and BH results).
+
tag= Apply a tag to a request. Only sets a tag once,
does not alter existing tags.
+
log= String to be logged in access.log. Available as
- %ea in logformat specifications
+ %ea in logformat specifications.
Any keywords may be sent on any response whether OK, ERR or BH.
All response keyword values need to be a single token with URL
escaping, or enclosed in double quotes (") and escaped using \ on
any quotes, whitespace or \ characters within the value
- For example: user="John\ Smith" or "J.\ O\'Brien"
-
- Request values sent to the helper are URL escaped to protect
- each value in requests against whitespaces.
-
- If using protocol=2.5 then the request sent to the helper is not
- URL escaped to protect against whitespace.
-
- NOTE: protocol=3.0 is deprecated as no longer necessary.
-
- When using the concurrency= option the protocol is changed by
- introducing a query channel tag infront of the request/response.
- The query channel tag is a number between 0 and concurrency-1.
+ For example:
+ user="John\ Smith"
+ user="J.\ O\'Brien"
+ user=John%20Smith
DOC_END
NAME: acl
For each requested URL, the rewriter will receive on line with the format
- URL <SP> client_ip "/" fqdn <SP> user <SP> method [<SP> kvpairs]<NL>
+ [channel-ID <SP>] URL <SP> client_ip "/" fqdn <SP> user <SP> method [<SP> kvpairs]<NL>
+
+
+ After processing the request the helper must reply using the following format:
+
+ [channel-ID <SP>] result [<SP> kvpairs]
+
+ The result code can be:
+
+ OK status=30N url="..."
+ Redirect the URL to the one supplied in 'url='.
+ 'status=' is optional and contains the status code to send
+ the client in Squids HTTP response. It must be one of the
+ HTTP redirect status codes: 301, 302, 303, 307, 308.
+ When no status is given Squid will use 302.
- In the future, the rewriter interface will be extended with
- key=value pairs ("kvpairs" shown above). Rewriter programs
+ OK rewrite-url="..."
+ Rewrite the URL to the one supplied in 'rewrite-url='.
+ The new URL is fetched directly by Squid and returned to
+ the client as the response to its request.
+
+ ERR
+ Do not change the URL.
+
+ BH
+ An internal error occured in the helper, preventing
+ a result being identified.
+
+
+ In the future, the interface protocol will be extended with
+ key=value pairs ("kvpairs" shown above). Helper programs
should be prepared to receive and possibly ignore additional
whitespace-separated tokens on each input line.
- And the rewriter may return a rewritten URL. The other components of
- the request line does not need to be returned (ignored if they are).
+ When using the concurrency= option the protocol is changed by
+ introducing a query channel tag in front of the request/response.
+ The query channel tag is a number between 0 and concurrency-1.
+ This value must be echoed back unchanged to Squid as the first part
+ of the response relating to its request.
+
+ WARNING: URL re-writing ability should be avoided whenever possible.
+ Use the URL redirect form of response instead.
- The rewriter can also indicate that a client-side redirect should
- be performed to the new URL. This is done by prefixing the returned
- URL with "301:" (moved permanently) or 302: (moved temporarily), etc.
+ Re-write creates a difference in the state held by the client
+ and server. Possibly causing confusion when the server response
+ contains snippets of its view state. Embeded URLs, response
+ and content Location headers, etc. are not re-written by this
+ interface.
By default, a URL rewriter is not used.
DOC_END
projects / thirdparty / squid.git / commitdiff
