From: Amos Jeffries Date: Sat, 10 Nov 2012 10:36:11 +0000 (+1300) Subject: Add squid.conf documentation for helpers X-Git-Tag: SQUID_3_4_0_1~471^2~7 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=5269ec0e4ea1b5ea194076eee2a10c569c7da4b4;p=thirdparty%2Fsquid.git Add squid.conf documentation for helpers --- diff --git a/src/cf.data.pre b/src/cf.data.pre index d21df75098..b85d5d560f 100644 --- a/src/cf.data.pre +++ b/src/cf.data.pre @@ -242,9 +242,22 @@ DOC_START "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. @@ -315,11 +328,22 @@ DOC_START "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. @@ -401,7 +425,7 @@ DOC_START 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 @@ -441,7 +465,7 @@ DOC_START 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. @@ -619,48 +643,83 @@ DOC_START %% 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 @@ -4072,19 +4131,54 @@ DOC_START For each requested URL, the rewriter will receive on line with the format - URL client_ip "/" fqdn user method [ kvpairs] + [channel-ID ] URL client_ip "/" fqdn user method [ kvpairs] + + + After processing the request the helper must reply using the following format: + + [channel-ID ] result [ 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